I hate comments
timothyfitz.com
I hate comments
1–10 of 55 posts
Re: I hate comments
#2the comments in the gc example are not there because the language this is implemented in is less readable than python; they are there because the problem the code solves is non-trivial and requires documenting. however clean, readable and trivial your code is, you can't express your thought process with it. and when you're doing sophisticated things, that is very important to convey.
Re: I hate comments
#3Hopefully no one even moderately unfamiliar with the language the code is written in needs to find out how to fix something that is broken. Citing breaking code by using some global that makes the comment no longer true? Sounds like an abuse of globals or someone not cleaning up the comments, not the comments themselves.
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.
Re: I hate comments
#4Sounds like the developers who wrote that code didn't know how to write comments. Here's some guidelines:
* 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.
Re: I hate comments
#5The comments that he shows are pretty worthless. However, comments are often necessary to explain WHY we are doing something.
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
Re: I hate comments
#6You can start to use your commit log as the comments.
Re: I hate comments
#7Comments can be super fun. Especially if you are into fabels and can liken the purpose of your code to the journey of a hobbit or similar creature from the shire.
Re: I hate comments
#8What a terrible and self-righteous post.
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.
Re: I hate comments
#9I don't mean to sound patronizing, but if you're implementing counters or banging out numbingly-boilerplate business logic for websites, comments are indeed useless.
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.
Re: I hate comments
#10I helped the author edit this post for clarity, but it took all I had not to argue with him because I strongly disagree with his thesis. My main language (Objective-C) is relatively less readable (compared to his main language of Python), and I would absolutely not be able to function in a team, or even with code I'd written myself over a week ago, without heavy commenting. I do believe he's right though with respect to test coverage being effectively a runnable comment or explanation of how a particular module works. However, to me at least, tests are no more readable than the source code itself, so I still rely (and implore my teammates to rely) on heavily commenting their code. Especially when dealing with inscrutable things like OpenGL code.