I want to try to get a sense of the set of reasons that people have for commenting or not commenting code. What follows is a table of blog posts (and similar) with an assesment of if they are generally for or against comments in code, and extracts which (I think) give an overview of their key points.
If you have any more links (perhaps something you have written) then please feel free to add them in a similar format in the comments on this post.
| Post | Position | Comment |
|---|---|---|
| The Hows and Whys of Commenting C and C++ Code | Pro | Comments should reveal the underlying structure of the code, not the surface details. A more meaningful comment would be “int callCount = 0; //holds number of calls to [function].” |
| Why comments in code are largely pointless | Anti | as we do the standard stuff we comment the code frequently and with confidence […] when it comes to something a bit more difficult we maybe have to try a few different options before we get it right […] there is little imperative to go back and document your work […] you get a large amount of commentary on the pedestrian every day part of your application and very little in the more interesting areas |
| Commenting Code Effectively: The How AND The Why | Pro | “why was it done that way in the first place?” […] Much like a math teacher asks you to show your work so that they can see how you arrived at the answer, a developer must comment their code as they are writing it to document (1) how the code works, and (2) why it was written that way. The developers thoughts and decisions are just as important in the comments as an explanation of how the code works. […] Make sure all methods and parameters are documented, explaining what is the purpose of each method and what are the expected parameters and results |
| The Problem With Comments | Pro | Comments should be displayed in the UI by editors as more important than the code (e.g. in bright colors) |
| Why would company develop an atmosphere which discourage code comments? | forum | |
| Comments are a code smell | forum | on balance probably pro |
| comments on code comments | forum | |
| Eliminating Comments: the Road to Clarity | Anti | It is not that comments in and of themselves are bad. It’s more that having comments in your code indicates that your code itself is not clear enough to express its intent. |
| Coding Without Comments | Anti | While comments are neither inherently good or bad, they are frequently used as a crutch. You should always write your code as if comments didn’t exist. This forces you to write your code in the simplest, plainest, most self-documenting way you can humanly come up with. When you’ve rewritten, refactored, and rearchitected your code a dozen times to make it easy for your fellow developers to read and understand — when you can’t possibly imagine any conceivable way your code could be changed to become more straightforward and obvious — then, and only then, should you feel compelled to add a comment explaining what your code does. |
| Common Excuses Used To Comment Code and What To Do About Them | Anti | (extensive extracts as post is no-longer available) Just two years ago, I was beyond skeptical towards the forces telling me that comments are worse-than-useless, self-injuring blocks of unexecutable text in a program. I thought the idea was downright ludicrous. But as I’ve made an effort towards reaching this nirvana called “self-documenting code,” I’ve noticed it’s far more than a pipe dream. […] you can choose better variable names and keep all code in a method at the same level of abstraction to make is easy to read without comments. […] want to keep track of who changed what and when it was changed. Version control does this quite well […] The code too complex to understand without comments. I used to think this case was a lot more common than it really is. But truthfully, it is extremely rare. Your code is probably just bad, and hard to understand. […] Natural language is easier to read than code. But it’s not as precise. |
| Don’t Comment Your Code | Anti | In the vast majority of cases, a comment indicates that something is wrong. If you have to add a comment to explain what a block of code is doing, that means that the code is too complicated or is using poor variable names or function calls. |
| Not Commenting And The Tipping Point Of Poor Programming | Not Sure | It’s one thing for a person, such as Brian, that writes very high quality code, to keep his comments to a minimum. But what about the majority of people who are not at his level? These are people who are not writing great code to begin with – are they going to view these blog posts as the excuse and justification to stop commenting their code? What happens then? We have an epidemic (as Gladwell would put it) of poorly written and poorly commented code. […] I am merely trying to play devil’s advocate to keep things in perspective. |
| Code Tells You How, Comments Tell You Why | Anti/Caveat | If you write your code to be consumed by other programmers first, and by the compiler second, you may find the need for additional comments to be greatly reduced. […] [code] can’t explain why the program is being written, and the rationale for choosing this or that method. [code] cannot discuss the reasons certain alternative approaches were taken. |
| Why programmers don’t comment their code | Pro | That’s probably not true unless you wrote it in COBOL. You may very well know that $string = join(”,reverse(split(”,$string))); just reverses your string, but how hard is it to insert # Reverse the string into your Perl file? |
| Why not to comment code | Anti | Every time you’re tempted to comment, take the time to think if you can make the code tell its own story, e.g., instead of some branching condition, extract the condition into a method to emphasize the story of why over how. Developers comment to explain a confusing part of their code rather than take the time to refactor it by extracting a method or naming a variable properly. Inevitably the code gets modified and the comment rots. |
| On Commenting Source Code – Why Commenting is Not Bad Practice | Pro | Maybe I’m missing something, but that’s not how I see the purpose of refactoring. When I refactor code I don’t arbitrarily break out larger functions into smaller functions that are only ever called once. Instead, I look for patterns that are repeated across the code base and try to create new functions that encapsulate those patterns. |
| Portrait of a N00b | Unknown | (couldn’t understand this post, a bit TL;DR combined with it somehow being a long missive on static types and if they are like comments or not) Should a team write for the least common denominator? And if so, exactly how compressed should they make the code? I think the question may be unanswerable […] I think the general answer to this is: when in doubt, don’t model it. Just get the code written, make forward progress. Don’t let yourself get bogged down with the details of modeling a helper class that you’re creating for documentation purposes. |
| comments are a sign of bad code and I am not sorry for saying it | Anti | Comments are not bad, the code is – I’m not suggesting to forgo the use of comments, but that they are only band-aids. […] Code should not be written to the level of the dumbest developer, the dumbest developer should be brought to the level of the code (though I want to reiterate good code should be easily readable). |
| How bad comments are born in your code | Pro | I don’t think going to the extreme and having comments replaced with just relevant class/method naming is a good idea because you cannot express full intent in a class/method name. This is actually why you have to write some code inside the class or the method, isn’t it? […] To summarize with only one word the reason for commenting code is maintenance! |
| Code commenting? Try Business Commenting. | Pro | one thing I rarely hear mentioned is that it’s often more interesting to comment the business justification than it is to comment the code. Jeff goes some way towards suggesting this when he says to comment the “why”, but for many people that translates to “Why did I write the code this way?”. I often find that code I’m maintaining is missing comments regarding the business logic. Rather than “Why is the code designed like this?”, something like “Why is the business process designed like this?” |
| Once Again: Comments In Code Aren’t Necessarily Bad | Pro/Caveat | I generally agree that you should strive to avoid comments in code. That is, you should write your code in a way that doesn’t require comments for the reader to easily understand and grasp what the code is doing. However… there are situations where comments are helpful (or even required) […] That code applies a certain pattern which isn’t well known, but there is a very specific reason why the pattern is needed. And I still believe that most developers need comments to understand it properly. […] if you need to write some code in a very non-obvious way, then you could really make things easier for those who need to maintain it […] by including some comments to explain why a certain solution/pattern was chosen. |
| Cleaning bad code | Anti | Even when comments are correct and useful, remember that you will be doing a lot of refactoring of the code. The comments may no longer be correct when you are done. And there is no unit test in world that can tell you if you have “broken the comments”. Good code needs few comments because the code itself is clearly written and easy to understand. Variables with good names do not need comments explaining their purpose. Functions with clear inputs and outputs and no special cases or gotchas require little explanation. Simple, well written algorithms can be understood without comments. Asserts document expectations and preconditions. |
| Don’t comment bad code—rewrite it. | Forum | |
| Good comments, Bad comments | Anti | Accoring to Robert C. Martin, comments don’t make up for bad codes. Instead code should speak for itself, by good naming & structure. |
| what makes beautiful code | Anti | Comments are code smells |
| When Should You Comment Your Code | Anti | Comment your code when it is hard to understand or determine your intent, because your code is crap. Yep, that is pretty much the best time to comment your code. When I was in college I was told to make sure that I commented my code. I always wondered why. Now I know. Comments really tended to clutter things and make it less clear what I was trying to achieve. I’ve written plenty of comments, but I know that when I use a comment that it means my code sucks. Comments take time to write, they take up valuable space, they add clutter, and they’re often out of date. So why do we write them? We write them because there is something confusing about some code. Or something that we need to tell future readers about the code. |
| Don’t comment your code! | Anti | it’s way harder to write good comments then no comments at all. So instead of making it all worse just don’t do it. If you consider yourself as someone who writes exceptable code, that should explain enough for you and your co-workers. |
| Should you comment your code? | Pro | Assuming that your code is good enough to not require any comments is very egostical. What is perfectly clear and logical to you because you have been working on a system for a couple of years will not be clear to someone who is new to the system. Put another way, code tells you how something is done and comments tell you why. |