Commenting Confusion – Should You Comment Your Code?

As a relatively inexperienced software engineer, one of the first things that struck me when working in a real dev shop environment was the lack of commenting in any of the code. This was contrary to university wisdom which suggested that everything be commented with an almost obsessive relish. I set out to ask the question – should you comment your code?

The question of whether a developer should always comment their code always seemed like a complete no-brainer to me in university.

No comments in your code? You obviously don’t know what you’re doing, subtract ten marks. This would be the standard reaction from a lecturer or marker if I handed in a university programming assignment with no comments in it.

So, imagine my surprise when, at landing my first development job doing Web application development, I realised with much dismay that none of the roughly 50,000 lines of code were commented. Literally almost none of them.

In fact, the only form of documentation whatsoever was a javadoc on some methods, which was of course very sparsely written and gave little indication of the code’s purpose.

Compounding this problem was the fact that the application I was working on was fairly complex, and none of the senior developers there really gave me much of a walkthrough on how the program worked, or even what it actually did, aside from a rudimentary introduction and brief mention of the key functionalities.

So, for the first few weeks, I was lost, up a creek without a paddle, frantically scrolling down pages and pages of code trying to decipher the meaning of method after method, of class after class and variable after god forsaken variable (the program was in Java, by the way).

Things got worse after I introduced several bugs into the program, through creating logic errors in my feeble attempts to code requested solutions despite me not having any real knowledge of the software’s functionality nor the inner workings. Needless to say, trying to find and fix these bugs I introduced was not fun.

Now I’ve since been told that this development shop probably could have done things a little better – giving me a formal induction and detailed run-through of the main application’s purpose and workings would have been a start – but, I’ve since learned rather interestingly that this is actually the norm in most modern development shops. Commenting is sparse, and downright non-existent compared to the near ceaseless stream of comments you are forced to insert into university programs.

I’ve talked to some senior developers about why commenting is so sparse in a lot of applications, particularly Web applications, and the answer is that, due to most development shops taking up agile methodologies and practices, most shops actually discourage the use of indiscriminate commenting in code. It’s all to do with saving time, working more efficiently, and reducing the risk of project failure.

See, what I failed to grasp is that excess commenting in code can actually increase your overall project risk. Why?

Imagine a scenario in which a developer rigorously documents each method, statement, and even variable declaration with well-written, detailed comments. All is well and good for a while, as new developers can easily find out what the intention of the code is by reading the comments.

However, after a while, let’s say a couple of years, some of the code has changed quite substantially. User requirements for the software have changed multiple times over the years and the program has been rewritten almost completely. However, the developers working on the code changes failed to update the comments. And why would they? It’s not expected of them to spend additional hours, days even, finding all the relevant comments to the code they are changing to make sure the meaning is clear. Hell, in an agile environment, that kind of time is far better put to use refactoring the code.

So now there’s a problem. The comments in the code are completely out of line with what the code actually does. Bugs appear, glitches occur, and developers freak out, consulting the outdated comments in a futile attempt to have a Eureka moment and figure out what the hell is going on.

A better alternative to extensively commenting code lies in a combination of regular code refactoring to reduce complexity, and writing a good unit test suite. Unit tests, unlike outdated comments, do not lie. They always describe the existing behaviour of a code – and the moment you change the behaviour of that piece of code, the corresponding unit test will fail.

Unit tests are really the ultimate way for developers to check for logic errors in their code and if they fail, it forces them to either update code to fulfil the program requirements or reconsider how to approach the problem.

There’s no glossing over or skipping ahead like you can do if you rely on commenting, leaving future generations of developers massive headaches when they attempt to fix the bugs you have created. It’s far better to have your specification and program requirements defined by unit tests.

There are probably some good reasons to comment, though.

I’ve never personally worked on any math-intensive programming, but I would think this kind of work requires a little bit more in the way of commenting – if you’ve got two or three nested loops using only i’s, j’s and k’s as variable names then yeah, commenting is clearly going to be needed.

Similarly, if you’re writing external-facing APIs such as a web application that will be executed primarily through API calls, you’ll want to provide comments so the developers who are using your code can gain some understanding of how to use your code.

You may also like...