On Comments in Code
henrikwarne.com
On Comments in Code
1–10 of 238 posts
Re: On Comments in Code
#2Code is for computers to make them do exactly what you want them to do, comments are for your co-workers (and you) to make them understand what you actually meant to achieve.
Re: On Comments in Code
#3The author touches on this a bit but I want to state this really simply:
Codes needs "why" comments, not "what" comments. The "what" can be done by self-documenting code, _most_ of the time. You still need to write "what" comments sometimes, don't rule it out completely. And you routinely need to write "why" comments, self-documenting code will never provide the context of "why".
Write more "why" comments.
Re: On Comments in Code
#4Code is for computers to make them do exactly what you want them to do, comments are for your co-workers (and you) to make them understand what you actually meant to achieve.
Code involves names of methods and variables which can greatly aid in understanding as well. I've always maintained that comments should only be in code to explain something that is not obvious.
If you're calling the SaveUser function and passing in a new User object that you had just created, a comment of "Save the new User object" adds nothing but noise.
Re: On Comments in Code
#5The author touches on this a bit but I want to state this really simply: Codes needs "why" comments, not "what" comments. The "what" can be done by self-documenting code, _most_ of the time. You still need to write "what" comments sometimes, don't rule it out completely. And you routinely need to write "why" comments, self-documenting code will never provide the context of "why". Write more "why" comments.
>Codes needs "why" comments, not "what" comments.
Indeed. While there are exceptions, "what" comments will usually only add noise thus making things more difficult.
This isn't necessary:
// Total count
int total_count = 0;Re: On Comments in Code
#6The author touches on this a bit but I want to state this really simply: Codes needs "why" comments, not "what" comments. The "what" can be done by self-documenting code, _most_ of the time. You still need to write "what" comments sometimes, don't rule it out completely. And you routinely need to write "why" comments, self-documenting code will never provide the context of "why". Write more "why" comments.
What belongs in comments describing API methods, why belongs everywhere else.
Re: On Comments in Code
#7Code is for computers to make them do exactly what you want them to do, comments are for your co-workers (and you) to make them understand what you actually meant to achieve.
Code involves names of methods and variables which can greatly aid in understanding as well. I've always maintained that comments should only be in code to explain something that is not obvious. If you're calling the SaveUser function and passing in a new User object that you had just created, a comment of "Save the new User object" adds nothing but noise.
A comment like "This method opens a separate database connection so as not to mess with the ongoing transaction" or some such would be rather helpful, though.
Re: On Comments in Code
#8Code is for computers to make them do exactly what you want them to do, comments are for your co-workers (and you) to make them understand what you actually meant to achieve.
I disagree. Code is not just for controlling the computer. Just as importantly, it's also meant to be read by humans.
So, code should be written in a way that is easy for a human to read and understand.
Code should easily and naturally show what it's intended to achieve 99% of the time.
Comments should be used sparsely, and only to express things that must be expressed and cannot be expressed in code.
Re: On Comments in Code
#9Earlier quoted context omitted.
Code involves names of methods and variables which can greatly aid in understanding as well. I've always maintained that comments should only be in code to explain something that is not obvious. If you're calling the SaveUser function and passing in a new User object that you had just created, a comment of "Save the new User object" adds nothing but noise.
A comment like "This method opens a separate database connection so as not to mess with the ongoing transaction" or some such would be rather helpful, though.
Within the code I write, I can't think of a scenario where that wouldn't be obvious. But if it is indeed not obvious, then I agree that would be a helpful comment.
Re: On Comments in Code
#10On the contrary, I find standard JSDoc and its variants to be an excellent tool for internal documentation. With hovering support in modern editors, it allows context explanation in a very streamlined and human way.
The author mentions for preconditions to just “read the code”. I consider this bad advice. If using an external library, would you rather hover over the method and see its conditions, or would you rather crawl into the third party source code?
I recommend that you treat the internal structures of your code as reusable third party libraries, and not assume that anyone will be familiar with it or how it’s used.
Often my JSDoc comments take up more vertical space than the code itself, sometimes even with ASCII tables or example usage code. I believe this is one of the best approaches to documentation, especially paired with a automated documentation site generator tool.
Code is read much more than it is written. You need to think like a writer and consider your audience.