The Design of Software (CLOSED)

A public forum for discussing the design of software, from the user interface to the code architecture. Now closed.

The "Design of Software" discussion group has been merged with the main Joel on Software discussion group.

The archives will remain online indefinitely.

Coding Standards

Hey all,

It seems like many of the places I end up we get the great idea of "coding standards" but when a project gets intense then everyone backs off and does what is necessary to get the job done. After which we look back upon our work and start again with the idea of coding standards... (the cycle repeats itself).

I was listening to a podcast with a VB "guru" Paul Sherrif who was essentially saying that "everyone's code should look the same" but that's very VB-ish and depressing. I'm sure a lot of the managerial people love that notion but then last weekend I was reading the introduction to the perl "llama book" where Larry Wall, the originator of the language, was touting the philosophy of perl and its design goal of allowing multiple ways for something to be expressed.

So where is my question in all this?  I guess I'm wondering if anyone has found a comfortable balance between standards, guidelines, and the occasional use of a ternary operator or "one-liner."

I'm also wondering if issues like this have more to do with language and culture - the solution to wanting to have flexibility, power, and ease is to find a design shop that uses perl or python vs. java or
David Seruyange Send private email
Monday, June 27, 2005
How it Looks and How it Works are completely different.
KC Send private email
Monday, June 27, 2005
There are some areas where this matter more than others and a couple where its crucial.

Space filled tabs and having the same tab settings.

This is crucial because if someone saves with TAB characters and the rest save with spaces then CVS will generate changes everywhere and unless you know to ignore whitespace it gets very messy.

If you have naming conventions then if you don't stick to them you might as well have written a rule that says "we don't know what we are doing and we prove it every day".  Which is not to say that you have to have naming conventions.

I prefer functional names rather than codes and ciphers which are external to the language or the data.  But I don't mind if they get used consistently, h for Handle, o for Object and so on.

The braces argument I care less about, if I can't recognise when someone is using fully indented or leaving the brace on the opening block line then I shouldn't be working in that language and if I haven't worked out that python works by indenting consistently I should go do something less strenuous, like write systme error message displays in VB or something.
Simon Lucy Send private email
Monday, June 27, 2005
> How it Looks and How it Works are completely different

Exactly my sentiments. I'd love it if the environment I worked in, except for the stuff Simon was mentioning (tabs, white space, etc..), could just trust each developer to write things as they see fit.

But in a lot of instances its that "weakest link" programmer whose code is responsible for a lot of bugs/problems that inspires these conversations.  For example, I see stuff like:

While reader.Read(){// } (missing a reader.Close in the braces _and_ for a query that returns a single record.)

I wonder if that is a code conventions problem or just a sloppy programming problem.
David Seruyange Send private email
Monday, June 27, 2005
> But in a lot of instances its that "weakest link" programmer whose code is responsible for a lot of bugs/problems that inspires these conversations.

Try for a 'coding standard' such as "Checked-in code will be bug-free" and then try to encourage/enforce/ensure that standard via code reviews.

Optionally, stop bothering to do code reviews on someone's code a few months after your code reviews no longer detect any bugs in their code.
Christopher Wells Send private email
Monday, June 27, 2005

There seems to be three types of coding standards:

1. Beautification.
2. Organization and Naming Conventions.
3. Heuristics.

Beautification entails things like where your braces drop, how many spaces to indent, tabs vs spaces, etc. This stuff should be automated as much as programatically possible. Many code beautifiers take as input a source file and a configuration file. Share the configuration file and teach people how to use it. Problem solved. It also kills the Religious-Brace-Style-Wars. For details:

Organization and Naming Conventions is refers to where put declarations, constants, privates, publics, class variables and methods. I use the following in Java: Constants, Private Variables, Constructors, Public Methods, Protected Methods, Private Methods, and then Accessor Methods. As far as Naming Conventions, most people follow the same set of rules, as set forth by Sun Microsystems. This is just something folks have to agree upon.

Heuristics is a higher level of conformance. This style is usually enforced in code reviews. It helps ensure that your code maintains its flexibility by adhering to good, modular, loosely coupled programming practices.
Dave Jarvis Send private email
Monday, June 27, 2005
I was going to comment on this topic, but then I remembered that I program in VB, so obviously I couldn't possibly have anything intelligent or useful to say.
Kyralessa Send private email
Monday, June 27, 2005
I noticed the new version on C# express doesn't even hav an option for "insert tabs as spaces".

It ONLY inserts spaces no matter what you do.
Overdesigning the Post-It Note
Monday, June 27, 2005
Your coding standards should be there to make life easier for you. Not now, necessarily, but in the long run. If you are dropping them under pressure, then either they are too difficult to follow, or you are storing up for yourself a maintenence nightmare.

The Beautification standards, like braces and indent, should be second nature to your programmers by crunch time. It frankly takes no extra time to write braces according to the standard than not according to the standard. Likewise for naming conventions and commenting code - five minutes now will save you hours later.

I think the more important question is: if your team feels under so much pressure that they can't take the five minutes necessary to ensure that code meets coding standards, then what else are they not thinking about before they check code in. one of the useful functions of coding standards, and code reviews, is to make you think about what you are checking in.
David Clayworth
Thursday, June 30, 2005
A good technical manager can easily enforce coding standards.  When a developer says that he has finished a task, the manager can glance through the code and see if it mostly matches conventions.  If not, he asks the developer to fix it and refuses to move the developer onto new tasks until it is done.  If the developer has already moved on to new tasks, the manager asks that he stop working on the new tasks and return to fixing coding conventions on old code.

Now, all the technical managers that I know (or have heard of) never do this.  Either they don't care, they consider themselves too important to look at other people's code, they lack discipline, or whatever.

Coding conventions are impossible to fix at the peer level but easily fixed at the management level.  A capable team can't compensate for a weak manager.
Daniel Howard Send private email
Thursday, June 30, 2005
I agree with David Jarvis' comments.

One think that standards help with is making it easier to train your eyes to reading code( Since most of us develop software as part of a team, a common style makes this easier.

I've been in organizations that have automated much of this process via static inspection tools and code formatters. If you really must view the code in your own personal style, then you can set up your editor to your liking, then run your code through the formatter before checkin.

Life is too short to argue over curly braces...
Former COBOL Programmer
Thursday, June 30, 2005
On pain of death the use of tabs in source code is discouraged.
cbmc64 Send private email
Sunday, July 03, 2005
In response to Daniel Howard, it is that simple the technical manager could look over everyones code to ensure it matches the standards. However as a technical manager myself I find that it's not that I'm too important or lack discipline is that I lack the time to check everyone in the team's code.

I'd much rather leave it to the team to peer review, where one of the criteria of the peer review is that it meets the coding standards. The team are all capable and professional people, does that make me a weak manager?
Steve Temple Send private email
Wednesday, July 06, 2005
If you can delegate it and the team follows through, you are certainly right about delegating it.

But, apparently, your experience is different.  From mine, peer review is not any more effective than self review.

A manager can delegate a task but it is still his responsibility to verify that the task was finished adequately.

Almost always, coding conventions fail because "everybody just sorta forgot all about it".  In most cases, this happens within 1-4 weeks of agreeing on the coding convention.  If you can do this long-term through a peer review system, you aren't weak; you're amazing.
Daniel Howard Send private email
Friday, July 08, 2005
In fairness I don't think we are 100% there yet. Especially as a project hits that final crunch before the scheduled completion date. I do think that the standards should be almost self governed without someone needing to make sure they are enforced.
Steve Temple Send private email
Monday, July 11, 2005
I loved the very first essay in Joel's new book that was on this topic... basically the author was arguing that compilers should enforce coding standards (including indentation, brace placement, that sort of stuff).
NetFreak Send private email
Wednesday, July 13, 2005

This topic is archived. No further replies will be accepted.

Other recent topics Other recent topics
Powered by FogBugz