Most people who've read Robert C Martin's Code Complete will probably agree. You write comments because you failed to write self explanatory code.
You can argue that you need comments in order to make it clear what the pre and post conditions are. But this is another argument for failure to explain this in code. Pre and post conditions could have been specified in contracts, but most languages have no or limited support.
Edit: most code quality tools will ignore comments when determining technical debt. This is wrong. Comments also need to be maintained and refactored. Wrong documentation is worse than no documentation.
Great topic choice Michiel,
I'm honestly not 100% sure where I stand on this one - whats your opinion about aiming to write code that doesn't need comments but using them sparingly when needed for the particularly complicated stuff? Is it best to take an all or nothing approach or is that just something to strive for?
If it is up to me (as I will not go against code convention of the project) I will write only why if it can be explained in a few words, max 2 lines.
As for doc-comments (i.e. method/class comments) I will write pre- and post-conditions if the language does not support this in other ways. As I mostly develop in Java I do use the null-annotations. And for the rest I document it in the method. I generally also declare all exceptions it will throw, even unchecked exceptions.
So in the end: I will always try to write code, which will read like a (weird) story. And leave out footnotes (comments) as much as possible.
There is no all or nothing. Just aim to write as little (code and comments) as needed without sacrificing readability. (See other comments about this).
Sure thing, that seems like the sensible thing to do, nothing worse than going to read a comment in code and ending up trying to get through war and peace. Thats interesting what you say with regards to Java, I use PHP a bunch and have really enjoyed some of the new return type hinting improvements made in the latest versions precisely for the reason you mentioned. The other bonus of this is I find it also helps minimise the number of tests I have to write because the entry and exit criteria are much more controlled and behave more predictably.
Thanks for the answer!
I'd argue that this is only in the case of "what" comments. If you write a comment that describes the operations taking place in a block of code ("what" is happening), then there is probably something wrong with your code. Code should be as human readable as possible. But I think that including "why" comments is still valuable. If you write a comment that describes the reason you made certain decisions in the codebase, it can be very helpful. I don't know how you could communicate reasoning and decision making without a comment.
Learned Fortran on an old TI-99; forgot Fortran; learned to draw, paint, sculpt, and play violin; learned how to merge code and art, turned it into my UX/Front-end dev Frankenthing.
I do still write what is taking place in a block of code, if only because what may be obvious to me may not be obvious to someone just starting out. Granted, my code generally is self-explanatory as far as I'm concerned (I could file it away, find it in a decade, and still know what it was for right off the bat), but I remember back when I was still had to look up why I could just use class and id interchangeably.
I consider it to be a sort of passive mentorship. Keep it short and simple, of course, but keep it clear enough that even a non-coder can get the gist of what and why.
The code I am currently refactoring is much more commented about how it used to work like A but now works like B, but not what A or B actually do, much less what the whole thing does.
While I think you should always write your code in a way that the next person can come along, read through and understand what the code does. I do however think comments are still necessary. The human readable code is great for reading what the code does. However, comments can provide what code cannot. Context. It was done a certain way because of x, y and z. It allows you to enter the mind set of the original coder. And their thought process in doing something a certain way.
Implementing algorithms from scientific whitepapers and having a customer that requires links to the whitepapers and explanations for any variations from the original algorithm (usually for performance).
Having comment-to-code ratio as a quality metric.
In general, though, most code I've written or reviewed has been pretty self-documenting. It gets tricky with numerical methods though, since we haven't fully embraced symbolic computing yet.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
Comments in code are a defect.
Most people who've read Robert C Martin's Code Complete will probably agree. You write comments because you failed to write self explanatory code.
You can argue that you need comments in order to make it clear what the pre and post conditions are. But this is another argument for failure to explain this in code. Pre and post conditions could have been specified in contracts, but most languages have no or limited support.
Edit: most code quality tools will ignore comments when determining technical debt. This is wrong. Comments also need to be maintained and refactored. Wrong documentation is worse than no documentation.
Great topic choice Michiel,
I'm honestly not 100% sure where I stand on this one - whats your opinion about aiming to write code that doesn't need comments but using them sparingly when needed for the particularly complicated stuff? Is it best to take an all or nothing approach or is that just something to strive for?
If it is up to me (as I will not go against code convention of the project) I will write only why if it can be explained in a few words, max 2 lines.
As for doc-comments (i.e. method/class comments) I will write pre- and post-conditions if the language does not support this in other ways. As I mostly develop in Java I do use the null-annotations. And for the rest I document it in the method. I generally also declare all exceptions it will throw, even unchecked exceptions.
So in the end: I will always try to write code, which will read like a (weird) story. And leave out footnotes (comments) as much as possible.
There is no all or nothing. Just aim to write as little (code and comments) as needed without sacrificing readability. (See other comments about this).
Sure thing, that seems like the sensible thing to do, nothing worse than going to read a comment in code and ending up trying to get through war and peace. Thats interesting what you say with regards to Java, I use PHP a bunch and have really enjoyed some of the new return type hinting improvements made in the latest versions precisely for the reason you mentioned. The other bonus of this is I find it also helps minimise the number of tests I have to write because the entry and exit criteria are much more controlled and behave more predictably.
Thanks for the answer!
I'd argue that this is only in the case of "what" comments. If you write a comment that describes the operations taking place in a block of code ("what" is happening), then there is probably something wrong with your code. Code should be as human readable as possible. But I think that including "why" comments is still valuable. If you write a comment that describes the reason you made certain decisions in the codebase, it can be very helpful. I don't know how you could communicate reasoning and decision making without a comment.
I do still write what is taking place in a block of code, if only because what may be obvious to me may not be obvious to someone just starting out. Granted, my code generally is self-explanatory as far as I'm concerned (I could file it away, find it in a decade, and still know what it was for right off the bat), but I remember back when I was still had to look up why I could just use class and id interchangeably.
I consider it to be a sort of passive mentorship. Keep it short and simple, of course, but keep it clear enough that even a non-coder can get the gist of what and why.
Comments are gold for people learning by hacking somebody else's code, i.e. almost everybody at some point.
They can be.
The code I am currently refactoring is much more commented about how it used to work like A but now works like B, but not what A or B actually do, much less what the whole thing does.
While I think you should always write your code in a way that the next person can come along, read through and understand what the code does. I do however think comments are still necessary. The human readable code is great for reading what the code does. However, comments can provide what code cannot. Context. It was done a certain way because of x, y and z. It allows you to enter the mind set of the original coder. And their thought process in doing something a certain way.
There are some cases where comments are absolutely necessary. Some examples from my career:
forloops for decreasing processing timeIn general, though, most code I've written or reviewed has been pretty self-documenting. It gets tricky with numerical methods though, since we haven't fully embraced symbolic computing yet.