Comments on: Five Rules for Writing Good Code

By: Pranab Ghosh

Pranab Ghosh — Fri, 05 Mar 2010 03:35:46 +0000

When reading code following the call chain for some use case, if you get the same feeling as when you can’t wait to turn the next page of a well written book, you know it’s well written software. Then reading software becomes as much fun as writing.

Pranab

By: Luciano Cheng

Luciano Cheng — Sun, 29 Nov 2009 21:47:28 +0000

Yan,

Great post.

Number 5, the point about knowing the language and the framework, is a style flaw that I see constantly. Some developers will code C like Fortran, C like C++, or Java like C++, without bothering to learn how to use a language or its framework. This in turn makes the code a nightmare to extend or debug later on by others.

For point 3, to add to the discussion above, I always keep in mind is that there are several common situations where you cannot avoid long functions, such as with OpenGL routines or GUI initializations. In these situations the function might be long, but perfectly acceptable if written in a self-documenting style.

By: Abhinav Upadhyay

Abhinav Upadhyay — Sun, 29 Nov 2009 13:50:15 +0000

Great tips!!! These are very important points and have a lot of importance in team based development.
The explanations make a lot of sense.

By: Michael Hoisie

Michael Hoisie — Sun, 29 Nov 2009 07:08:25 +0000

Great post. I definitely agree with the #4, your code should be idiomatic for the language you’re using. I’d probably suggest to seek code reviews from people who are smarter/more experienced than you.

By: Yan

Yan — Sat, 28 Nov 2009 23:58:47 +0000

@Thor I also think it’s true that 5 line methods are easier to unit test than 200 line methods. Given that you are testing your code, I would expect error rates to be reduced in 5 line methods. Of course it’s possible people get lazy and don’t test the 5 line methods because they assume they can understand all the implications, whereas everyone is afraid as hell of a 200 line method so they test it really thoroughly.

By: Yan

Yan — Sat, 28 Nov 2009 23:52:55 +0000

@Thor that is an interesting bit of research. But my post is not about error rates, but saving people’s time in maintaining your code. I think it’s still true that short routines are easier to immediately grasp, especially if the method is properly named.

@landondyer to be sure, what I’ve written is not gospel, and is not always true. But if I write a post that says “sometimes short functions are good and sometimes long ones are good” it loses all its flavor and point. You are right, nested function calls to small functions can be a pain – but I think nesting is probably a code smell in and of itself and doesn’t necessarily have to do with method length, but rather how the code is organized, and how objects are interacting with each other.

I love the “tell a story” concept, that is exactly what I meant when I said that the code should read like a recipe. Meaningful method names, and keeping things on the same order of abstraction within a method is what helps tell the story. Usually, if the story is told well you don’t need to look inside the subchapters/sub-methods to see how they work, you can read the ‘table of contents’ which is a method consisting of calls to meaningfully described methods. Conversely you can look at any submethod and understand it entirely just by its name and simplicity of its code.

By: landondyer

landondyer — Sat, 28 Nov 2009 23:41:56 +0000

The best programs I’ve read or had to maintain “tell a story.” It’s a lot like reading Hemmingway; short bits of code interspersed with high-level guidance in comments. The code is spare and lacks bells and whistles; it does what it needs to do and no more.

Using plenty of whitespace helps a lot, too.

I work on a system that does have a lot of 100 line functions. I don’t think it’s that bad; while it’d be nice to get on a “large functions are eevvvilll” warpath, I think that other qualities of code are much more important, and there are 300 line functions written by adults that are easier to read than 20 line functions written by people who just seem careless. (The “let’s make functions 5 lines long” school of thought makes my head spin whenever I get eight or ten method calls in).

By: Thor

Thor — Sat, 28 Nov 2009 22:41:32 +0000

In fact, in Code Complete, Steve McConnell discusses how most research shows no correlation with routine length and error rates – an in fact, at least one study showed that shorter routines are more prone to errors. A counterintuitive result for software quality authorities, no doubt.

By: Yan

Yan — Thu, 01 Oct 2009 14:34:35 +0000

Yes, of course you are right – comments explaining Why are not a bad idea. However, almost always the right place for comments is outside of a method/class/chunk of code depending on your paradigm, explaining why the method does something. When you find them interspersed within a large method it usually means the method itself is too long. Inline documentation is not inherently bad, it’s just bad when it’s used as a substitute for breaking code down into small, easy to understand functions with self-descriptive names.

By: Nathan Leach

Nathan Leach — Thu, 01 Oct 2009 12:52:35 +0000

Yan,

Nice, concise list of rules. I like them all. I would add that comments can be useful in the sense that you can say “why” you are doing something…the “how” should be the clear part in the code itself. What do you think?

I do mostly corporate development, where standards dictate a certain level of inline documentation. It takes a lot of time and effort to change those rules (sigh).

Keep up the good work!