In computer science, you are taught to comment your code. When you learn a new language, you learn the syntax for a comment in that language. Although the compiler or interpreter ignores all comments in a program, comments are valuable. However, there is a recent viewpoint that commenting code is bad, and that you should avoid all comments in your programs. In the 2013 article entitled No Comment: Why Commenting Code Is Still a Bad Idea, Peter Vogel continued this discussion.
Those who believe that commenting code is a bad idea argue that comments add unnecessary maintenance. When code changes, you must also modify comments to keep them in sync with the code. They argue that it is the responsibility of the programmer to write really obvious code, thus eliminating the need for comments. Although these are valid reasons to avoid commenting code, the arguments are simplistic and general. Comments are necessary for a variety of reasons:
There are many important reasons to comment your programs. Although commenting may be tedious or overwhelming, it is valuable in many situations. Even if you think you write really obvious code, try reading your code months or years later. Will it still obvious to you, or would you wish for comments?
Edwin Torres is a full-time software engineer at The MITRE Corporation and an adjunct professor of computer science at Monmouth University. Follow Edwin on Twitter @realEdwinTorres.
I had a client once with the no-comment rule.
I could not read the client's code, even though it was quite well written, immediately killing the premise of the pure no-commenters.
The reason is simple: using English to elicit a mental map of the code within the entire codebase is crucial for quickly remembering where you want to make updates. Without this hint, the coder will be continually re-learning in an inefficient manner.
And in general, I believe this to be evidence of a general rule: some organizations would rather increase implicit labor cost than increase explicit code size. "Driving costs to the edge", they call this in the military.
I do quite agree with Peter, though, that using comments at the function/method level is sufficient almost all the time. I just need the mental map, not some potentially inaccurate re-hash of the logic.
Mark- Thanks for the comments. You summed it up well. There definitely is an implicit labor cost (inefficiency) regarding commenting, with both too few and too many comments.
I do a lot of maintenance of other people's code (and my own that I don't fully remember), and my commenting principles come mostly from the question "what would make this easier". The most important is "is it *locally* apparent to a competent coder in this language what is going on here". If so, a comment would provide minimal benefit, while still suffering from the usual problems of code cluttering and not being kept up-to-date. If not, a comment is called for.
By "locally", I mean you don't have to search out additional information from many far-flung places, especially if there are not easy direct paths to the relevant places.
As a simple example, when there is a subscript value being used to keep track of how much of an array is occupied with meaningful information, there are two common alternative invariants. Either the subscript points to the last occupied element, or the first unoccupied one. You could infer this from careful reading of any one use, if only you knew for certain that whatever the invariant is, it is followed consistently. When doing maintenance, you are asking for trouble if you make this tenuous assumption. If there is any doubt, to avoid fixes that induce more breakage, you must locate them all, and make them consistent if not already so. And once done, add a comment at the relevant declaration point, for the benefit of any poor wretch who should fall into this web again. It could be you.
This is even more important when the needed information is not even in the software system you are working on. Examples are a compiler that supports multiple target machine/OS combinations and a debugger that has to work with multiple compilers. Or just any imperfectly-documented library code. (Can you assume a perfectly-documented library exists?) Sometimes you have no control over these outside software systems, or even access to their source code.
I always modify or add comments documenting any information that was hard to dig out.
Rodney- Thanks for the insightful comment. Your example supports the notion that there is an art to providing good comments. I recently read comments that made me wonder if they were no longer valid. They were "TODO" comments, and I could not tell if the functionality was already implemented.
The topic on writing comments or not is very broad.
Comments can be badly written with reasons ranging from not mastered second language to missing maintenance.
Edwin, what do you think you could have done? How could you know, at the moment you wrote the code, what comment would help you in the future? I don't think it is an easy task to make the right decision. Too many things can change between the moment we write code and months or years later when we need to read the code.
If it is hard to write code that is easy to read, I think it is equally hard to write well structured comments that will not get in the way later. Plus, there is no way to proof the comment is correct other that by looking at it with the eyes of the future readers.
I also think we try to move too fast from beginner to seasoned programmer. If we could pair beginners and masters to help learn the craft then maybe we could improve our art - code and comments alike.
Hugues- You may very good points about writing and maintaining comments. I especially like your comment about moving from beginner to seasoned programmer. I agree with you. That is not something that can/should happen overnight. Only with time and practice can you become an advanced programmer. Thanks.
Displaying comments 11 - 16 of 16 in total