So many times I have had to repair code in languages I wasn't quite familiar in or that was simply using methods I hadn't learned yet. Those comments were life saving.
Comments describing intentions of code also allow for someone to come by later and quickly and concisely understand what the code was doing and where it was going.
I cannot think of a single instance where parsing 65 lines of a function definition was ever quicker than reading:
This method takes a foo object, applies HTML encoding, and returns an array of the original and the clean code.
In the same vein, saying that Unit Tests are a replacement for comments just brings me back to my original assertion: I already am looking for help understanding the code base, so I should look at more code elsewhere and parse another long list of assertions?
Bad comments are bad like bad code is bad, or like bad pie is bad. But comments, code and pie aren't bad.
Please don't stop commenting your code because you feel like you can be more clever with the language instead. Someone may be much more familiar with the language the comments are written in. They may may need to do something with what you wrote.
Whenever I read some new reason why comments aren't cool or why some programmer has decided they[1] can just be clever with the language, I can't help but think they just don't have enough experience to know why and how comments can be absolutely necessary and fantastic.
[1] not saying this is necessarily true in this case, it's just the impression I get.
def clean(foo)
return [foo, foo.apply_html_encoding]
end
I would consider that comment just as bad as the ones in my examples, but maybe not quite as obviously so.
It also has the side effect of being in a different file to the one you're trying to read.
But as you say, they need to be good comments, and comments that either describe intention or explain something in the language that might be rather obscure can be very useful.
* Anything that duplicates the line they describe in prose should absolutely be removed. They're worthless and become out of date immediately.
* If you have logical "paragraphs" of code separated by newlines and comments summarizing the paragraph, that's a great indication that your parent method/function/whatever is in charge of doing too much. Turn the comments into names of new methods/functions and refactor accordingly.
* If the algorithm is sufficiently complicated, it definitely deserves a documentation block describing the "how"s and "what"s. But more often than not those comments are just a duplication, as specified in the first bullet point above. If you don't think any code ever deserves these sorts of comments: congratulations, you've never worked on anything non-trivial in your career. I suggest that you find more of a challenging project.
* Definitely leave a comment behind explaining the "why"s behind a particular block of code if its intentions are not immediately obvious.
* Definitely have headers of documenting comments for functions/classes/methods/parameters/etc. Is your first reply when someone asks "How do I learn to use Rails?" to say "Read the entire source code to Rails"? No, of course not. For the same reason, your reaction to "How do I use this block of code" should not be "Read the block of code." Abstractions and proper APIs people, come on. I should be able to glance at the docs above it along with the definition and know how to use it, what to pass to it, and what I might expect in terms of returns / side effects. Bonus points if you have a tool to auto-extract these into a static site that you host for your team.
How is a test case supposed to explain why MAX_COUNTER is set to 5 or 20? Comments are the single-most important thing when writing code, in my opinion. When feature specs are lost, and documentation goes out of the date, you only have code. And if you're supposed to jump through hoops like test case code to try to divine WHY things are as they are, then you're dealing with really hard-to-maintain code.
I strongly suggest all developers to ignore this blog post, and to comment as best as you can.
Bad or to many comments are better then no comments. Its not exactly hard to remove them, their absence will never break the build unlike not understanding the implementation!
God help the guy who rips out a seemingly innocuous line of code only to subtly break things underneath. Even a simple:
// Hack around time parsing bug in iOS3+, see [StackOverflow thread]
We can get rid of comments the moment we invent a perfectly expressive language, where every single line of code in your entire stack is under your control and everything works exactly as advertised out of the box.
Until then, I'll keep commenting where I need to, and never when I don't.
oven.setTemp(350) // 400 will burn them, 300 they will be mushy
fluxCapacitor.setOption(THRESHOLD, 1.21E9) // lower thresholds will prevent return from time travel. Please see http://en.wikipedia.org/wiki/DeLorean_time_machine to review the physics
function setTemperatureToCookPerfectly() {
oven.setTemp(350);
}
function ensureReturnFromTimeTravelPossible() {
fluxCapacitor.setOption(THRESHOLD, 1.21E9)
}
To quote one of the Ruby Rogues, "A comment is a lie waiting to happen."
Granted I would personally do:
const int perfecttemperature = 350; // 400 will burn them, 300 they will be mushy
.....
oven.setTemp(brownie.perfecttemperature);
What if later it is determined that the proper temperature should instead be 375 because at 350 they aren't quite cooked enough?
1) Why the code is doing what it's doing. What's the motivation? Why is a check necessary? What's the context?
2) High-level overview. 20 lines of code may speak for themselves, but a quick sentence can easily summarize it. I love well-summarized code. "Do X with the Y unless it's Z" is a really fast read. (Function names obviously provide this sort of explanation, but sometimes a name is not obviously not always sufficient.)
3) Stubs / future notes. Sometimes you need to leave something stubbed out. If you have thoughts on what they code will need to be, leave a note about it. This is easily removed later.
4) Quirks. If the code does something that is not obvious, note that. Non-obvious side-effects, bugs, etc. Don't discover something painful, then leave the next person (possibly a future you) to re-learn that same painful lesson.
Code does stuff. Comments describe the code. Comments should not re-describe what the code does, they should be about the code and the code's context itself.
1 & 2 are both better solved with method abstraction. Comments describing what code is doing is always a code-smell to me. If you have 20 lines of code that is non-obvious, think about extracting it to one or more well-named methods.
// unroll loop for 50% speed increase. Optimal offset 4
// 3: 25%
// 4: 50%
// 5: 40%
for(i=0;i<x;i+=4) {
...
}
2 is definitely more an opinion, but I use XML comments on every function, object, parameter, return value with a quick summery because it integrates into my IDE and is used to generate API and library documentation that is invaluable to developers who don't necessary have the code, only the documentation.
Why is the counter < 5 or the balance >=0? Comments explain why your assertions are reality. Not every assertion is going to be as obvious as "balances have to be positive". If I had a dollar for every opaque assertion I blew up or ran into in code that had no explanation as to why something had to not be 0 or >1mil or null or whatever I would be a rich man.
But when you're reading an obtuse 50-line function that implements some weird algorithm acting on some weird data structure, full of magic-like assumptions, you'd wish no one had deleted comments from it, or... had written them in the first place.
Implementing an advanced data structure is a good example of this. Things that took theoreticians some time to discover, and write/publish in a paper, are not things a random programmer is just going to inherently know from a completely uncommented implementation.
Extrapolating "all comments are bad" from a few examples of pointless comments on mind-numbingly simple and obvious code (which are indeed bad) is silly.
I have one particular piece of code, that I wrote, in mind. It was to implement anonymous methods in the Delphi compiler. Given an AST for a method from the parser, it had to rewrite the tree to turn captured local variable references into field accesses on a heap-allocated stack frame, turn anonymous methods into methods on this heap-allocated stack frame, and all while minimizing the number of passes over the tree. And this has to work recursively, which adds a surprising number of wrinkles about the ordering in which you can do things.
So for example any given pass may be building up accounting data needed by later passes. This is somewhat mysterious, because it seems like busywork; and why is it doing this here? Why not fold one pass into another? Why not move work between passes? Well, the subtle ordering problems are not clear at all when you're looking at things at the function level. You can only understand the pieces when you already understand the whole.
And this is why there is a very long comment block describing how this stuff works. Because figuring it out by reading the code is too expensive.
(That ~1000 lines of code took perhaps 4 months to write; having to integrate with rest of a large complex codebase adds countless more wrinkles.)
Not to mention how test cases and function names would just not cut it for explaining things like why the current implantation was chosen over more obvious, simpler ones, why the magic like assumptions are necessary and documenting the bugs/quirks in the underlying library or framework that are not obvious. Things like why call object.SetValue() instead of property object.value = x? Or Free memory from this call here, but not here, because the framework takes care of it.
I prefer commented code, even if it is over commented, because at the very least it is a way for the last programmer to explain why she implemented things the way she did.
Do you leave unused functions in your code when you refactor? No. So refactor your comments, or delete them if they are no longer applicable, when you refactor your code.
I have been saved many times by comments in my own code, because you know I work on a lot of stuff, sometimes coming back to it after years and I hope I have developed as a coder and so my mindset is now different and a lot of the time I do wonder WTF was I doing here!
This is the opposite of your post http://tech.collectedit.com/post/2012/11/12/Comment-your-dam... which I tend to agree with a lot more.
Your code tells me what you did. Your comments tell me what you intended. Help me out. Help your future self out!
Also, sometimes the code is sufficiently brain-compiled that it's utterly inscrutable. Early in my career I wrote a fast interrupt driver for the company's main product that had become quite heavily optimized, and practically every line depended on nuances of the related hardware's functionality. This code was written in two-column code/comment form, and had more lines of comments than lines of code. This was necessary for it to be at all maintainable. In theory, a later refactoring might have simplified this state of affairs... but that opportunity never happened.
Everything in Java is Big Deal, even something like a simple loop going through a collection and applying a one-liner to every element. In Java, you have to divide things aggressively for code to remain readable and maintainable. Otherwise it's way to easy to lose the big picture.
When methods are few lines tops, their names are descriptive, and you have explicit types of arguments and return values, it's no wonder you hardly ever need to comment anything.
Other languages can be very different in this regard. Take Python, ironically the language author's using in his examples.
Python is terse and expressive; does not specify types in code; has everything as first-order values; prefers short names due_to_naming_convention; and makes extracting code into functions a significantly bigger deal (everything is public, needs to have docstring, etc.). Those traits often need to be offset by a little more prose than you would put into code in other languages.
So while Clean Code certainly sounds convincing (I know I treated it almost like a revelation), it needs a little more perspective. Commenting practices are just one more tool that you need to match to the job - and language - at hand.
Him: I don't write comments. My code is self-documenting.
Me: Apparently, you have never attempted to read those documents.
Most developers are under at least moderate pressure to deliver and usually their priority is this...
1) Make thing appear to work
2) Make thing actually work
3) Clean up code to pass a code review or not be yelled at by a coworker
4) Comment where things are necessary
In many cases we barely get past step 1 and a half and usually its not even our fault - the business case has been mostly satisfied and according to the mucky mucks its best to move onto the next feature. Yes most of us dream of places where we can craft our code to oblivion but its probably not the average reality unfortunately.
I think its great when somebody takes the time to comment - commenting is not fun and has very little upfront reward but can be a lifesaver when traversing complex logic. If you have the ability to leave a profuse amount of comments I can hide them when I dont need them and use them when I have no idea whats going on - comment as much as you like.
I put XML comments on every function, object, property etc giving them at the very least a short summary. These are then compiled into documentation xml that integrates with the IDE providing pop-up documentation for objects and functions without needing to see the source code. This xml is then compiled into actual html documentation is also used for APIs and libraries that other developers use without any access to the code.
Maybe documentation falls outside of the purview of source code comments... but i don't think so and i find it really handy to have the source code self documented with comments keeping docs and code in the same place.
Try expressing a relatively complex state machine with asserts. Then come back in a month and try converting all those asserts back into few English sentences.
If we as developers spent more time on using better names for our objects/methods, we would need less comments.
But seriously. Comments are useful. Don't over use them, don't under use them. If you are being dogmatic about your comments, you are probably doing it wrong. Autodoc comments can be nice, when done properly.
Comments suck, documentation rocks.