Adding more noise to the "Code Comments" debate

For the record, before I get started I have to state that despite where Jeff Atwood has gone lately in editorial terms, I have a great amount of respect for his blog and the work he's put into it over the years. As a contractor, I move around different companies quite a bit, but one of the constants has always been the frequent, thought provoking team discussions which have arisen as a result of one of Jeff's posts. But ever since Jeff typed the now immortal phrase "strong opinions, weakly held" the majority of people I have spoken to think he is ever-so-slowly losing the plot. It does seem that a lot of his posts lately have been triggered by some experience he's encountered during his work on StackOverflow.com, and while there is obviously nothing necessarily wrong with that, I do wonder if the bubble he has found himself working in is skewing his perspective a little.

The post which finally drove this blog to state its own position is this:

Coding Without Comments

Unlike some of his other posts, specifically the one about #regions, this one I've read all the way through several times, and made sure I read it through again before I writing this post. And basically the whole thing leaves me with such a bad taste in the mouth that I can barely believe what I've been reading.

Like it or not, Jeff is read by many developers across the spectrum of ability and experience. Young and new devs are sent links to Jeff's posts and are over time gradually eased into the Atwood Cult. I feel as though in this one post Jeff has potentially done some significant damage to the hard work that all of those people, like myself, who as part of my job try to encourage others to write clear code and write good comments. It has handed on a plate an excuse for those devs who are too lazy, or disenfranchised in their jobs (the job security excuse), to bother putting any comments in the code that they churn out.

To try to keep the rest of this concise, I'll list my views on this as bullet points:

• I won't go too far into any of the examples in Jeff's posts as clearly they are carefully chosen to prove the point. What I will say though is that his refactoring of the SquareRootApproximation by extracting the method did not, as he says, make the code "perfectly understandable". He's made the use of the code understandable, but not adding comments, or breaking up the string of operations, is creating code that is probably difficult to maintain.

• We don't all work with our friends or with people we've worked with for years and so understand how they tick.

• Encouraging people to use better naming for variables and methods etc is an exceptionally good thing, and I think this is probably where the emphasis in Jeff's post should have been. The policy of this blog is that code reviews are king, and code that is written with a bias towards readability, and therefore more suited to review, should be encouraged even if this results occasionally in less than optimal implementation, and maybe produces slightly larger source files.

• There is such a thing as too many comments. I have a running joke with a particular developer I have worked with a couple of times that he over-comments his code. Taken to an extreme, comments which mindlessly state in verbose English the simple to understand operations that follow, do harm the ability to read and review code, as they add unwanted noise.

• In terms of the argument for better naming of constructs and members rather than comments, I strongly believe that it should not be a case of either/or it should and must be BOTH.

• Maybe Jeff can be forgiven for being US-centric but the overriding notion you get from his recent posts kind of implies that every team can and must be occupied by top tier, highly experienced and capable coders. If a team member isn't up to the task then it's in the team's interests to drop them and find another. This is a fine and noble sentiment but for a few flaws: Not every developer can be the best of breed. In general, especially in the UK, we have a skills shortage and in particular a shortage of high quality, experienced software developers. (The reasons for this are largely political and mainly due to the current government's attempt to destroy our IT industry, in favour of promoting the agendas of the large consulting firms, but that is a post for another day.) The net result is that the industry is filled with developers wholly unsuited to software development and have moved to careers in IT as an easy route. They are everywhere, both contractors and permies, and are writing ream after ream of code, with barely a consideration about how that code will be maintained or supported. These are the people who will use Jeff's posts to argue that comments in code are pointless.

• One of the big anti-comments arguments is that they can become out of date in relation to the code they comment. My response to this is that COMMENTS ARE AS IMPORTANT AS THE CODE and deserve the same level of attention during modification of code as the compilable stuff itself. The argument that comments quickly go out of date should not hold water.

I could go on, but won't. I'll end by saying that in the real world, real software is over-complex, over-engineered, written under time pressures, often by people who's skill in the art is below average. They are expected to hammer out the code, those with the inclination to refactor are often not working in an environment where such things are encouraged. After all this, other people will have to fix and maintain the code and without comments, of any kind, this type of software which is being created ALL OVER THE WORLD RIGHT NOW is made all the more substandard because of it.

We can't all code in utopia.