Skip to content

Writing and Programming – brothers in arms

This rather in depth article called Does bad writing reflect poor programming skills? by J. Timothy King (his blog’s byline is ‘Entrepreneurship for Software Developers who want to change the world’ – brilliant) is a good read, and it makes for a fine excuse to waste time blogging when you should be programming :-P

There’s only one bit of beef I have with the article. He includes an unreadable (but commented, somewhat) code sample and then rewrites it to something much simpler and more readable. The rewrite has no comments. This snippet is followed by:

Sometimes fewer comments makes for more readable code. Especially if it forces you to use meaningful symbol names instead

Let me add to this: In 90%+ of the cases, this is true. If unsure, do NOT comment, instead, fix the code so it is intrinsically readable. Stuff your comments on function definitions (and only there if truly neccessary. This depends a bit on how prosaic your language gets when defining functions. E.g. in python it can make sense to clarify the nature of the returned data, whereas in e.g. java documenting that some method ‘returns a list of all users in the system’ is probably pointless if the return type is already Collection<User>.

Said differently, comments are also to be considered as lines of code ‘spent’ – they are a blemish. First, only comment if you must, and, second, in such situations, try and tweak the code so that the comment is no longer needed because it has become obvious due to refactoring e.g. the structure. Usually you can off-load the tricky bit into a method and document the method.

{ 2 } Comments

  1. Tim King | 2006/12/16 at 18:47 | Permalink

    Hi, Reinier. Excellent point. I agree. In at least 90% of cases, a comment is a code smell. And when you do need them, comments should tell why a piece of code is there, but not what it does. If you feel you need to say what a block of code does or what a variable is for, you probably need to pick a better function or variable name.

    -TimK

  2. rzwitserloot | 2006/12/16 at 23:29 | Permalink

    “Code Smell”? Never heard that term before. I like it!