The second and third point is contradicting: if you write clean and readable code, you don't need comments everywhere. For clean code, I would recommend the book Clean Code from Robert C. Martin
The comments OP talks about in the second point seem to be documentation comments - a totally different beast than the comments clean code advocates warn about.
It does matter. According to the clean code philosophy, you should avoid writing comments to make the code clearer and instead refactor the code so that one wouldn't need comments to understand it. Documentation comments are for generating API docs, so it makes sense to have them even if you follow clean code principles.
The cleanest code still takes more cognitive energy to understand than plain natural language comments. I don't see the need to strive for less comment. Every function, class, or module should have comments. Especially when today's tooling can easily generate docs out of them.
a good expressive comment at every abstraction level is an indication of a well-thought-out design from the developer. The same indication can be evident from a unit test.
If you need more cognitive energy to understand than it is not the cleanest code in my opinion. Comments are always longer and can quickly become obsolete. Nothing enforces them to stay up to date...if you forget it, it remains there unnoticed.
I disagree. In languages like C/C++ or Rust, how ever clean the code is you still can't comprehend easily the intention until you've read through a few lines into a function.
In Go, every exported function is expected to have an accompanying comment. That's considered good practice.
I think it depends on codebase. If its small then code can speak itself what it is intended for. But if it's larger codebase then there should be comments to briefly explain the intentions of programmer.
Thanks for your comment Gábor Soós. Yeah @blacksonic
. I agree that if code is readable and clean then you don't need comments but I think there may be cases at time when you are doing some complex calculation or manipulation, then in larger code bases it may be better to put a proper comment there.
Coding since 11yo, that makes it over 30 years now ~~~
Have a PhD in Comp Sci ~~~
Love to go on bike tours ~~~
I try to stay as generalist as I can in this crazy wide place coding is at now.
Totally agree!
The senior devs I've worked with tend to end up removing more comments than they add.
Excessive comments tend to be removed during peer review.
Comments are essential where it's hard to get the intention of the code by reading it, which is sometimes unavoidable but should be the exception not the rule.
Clear code shouldn't need comments. Tricky code does. No use filling your codebase with tricky code.
Yeah. Comments should be removed in peer review. They are just to give understanding of something tricky. Complex code should be avoided if it's not needed.
Aging Java back-end guy. Ironically although I got my github thinking I'd fill it with nifty stuff I'd do in Java on my own time, I've ended up sticking a load of JavaScript on it instead!
Comment to document the why of the code, not the what. What it's doing should be immediately apparent, but why the client wants it to do that may be important for future maintainers. The last thing you want is for some new dev to rip out something that makes little sense, only to find themselves hauled into the CTO's office to explain why they've gone against the client's wishes & be embarrassingly made to restore it in an emergency release.
Good recommendation. Many -- perhaps all -- developers would benefit from reading Clean Code, even if they don't agree with every word.
I tend to agree about comments. Expressive code shouldn't need endless comments. That said, there are times when the code can't tell the full story -- if it's doing something funky, or you want to explain your design decisions. In these cases, comments are definitely needed.
The second and third point is contradicting: if you write clean and readable code, you don't need comments everywhere. For clean code, I would recommend the book Clean Code from Robert C. Martin
The comments OP talks about in the second point seem to be documentation comments - a totally different beast than the comments clean code advocates warn about.
It refers to comprehensive comments. It doesn't matter whether they are to serve as a basis for documentation or making code clearer to new developer.
It does matter. According to the clean code philosophy, you should avoid writing comments to make the code clearer and instead refactor the code so that one wouldn't need comments to understand it. Documentation comments are for generating API docs, so it makes sense to have them even if you follow clean code principles.
Yeah. It matters but I am in favour of what I said.
The cleanest code still takes more cognitive energy to understand than plain natural language comments. I don't see the need to strive for less comment. Every function, class, or module should have comments. Especially when today's tooling can easily generate docs out of them.
a good expressive comment at every abstraction level is an indication of a well-thought-out design from the developer. The same indication can be evident from a unit test.
Yeah. Both things are necessary i.e expressive comments and cleaner code.
If you need more cognitive energy to understand than it is not the cleanest code in my opinion. Comments are always longer and can quickly become obsolete. Nothing enforces them to stay up to date...if you forget it, it remains there unnoticed.
I disagree. In languages like C/C++ or Rust, how ever clean the code is you still can't comprehend easily the intention until you've read through a few lines into a function.
In Go, every exported function is expected to have an accompanying comment. That's considered good practice.
I think it depends on codebase. If its small then code can speak itself what it is intended for. But if it's larger codebase then there should be comments to briefly explain the intentions of programmer.
FYI: The author of your linked book is not Martin Fowler ;)
Thanks, I tend to mix them up, but the book is certain :)
Thanks for your comment Gábor Soós. Yeah @blacksonic . I agree that if code is readable and clean then you don't need comments but I think there may be cases at time when you are doing some complex calculation or manipulation, then in larger code bases it may be better to put a proper comment there.
Totally agree!
The senior devs I've worked with tend to end up removing more comments than they add.
Excessive comments tend to be removed during peer review.
Comments are essential where it's hard to get the intention of the code by reading it, which is sometimes unavoidable but should be the exception not the rule.
Clear code shouldn't need comments. Tricky code does. No use filling your codebase with tricky code.
Yeah. Comments should be removed in peer review. They are just to give understanding of something tricky. Complex code should be avoided if it's not needed.
Comment to document the why of the code, not the what. What it's doing should be immediately apparent, but why the client wants it to do that may be important for future maintainers. The last thing you want is for some new dev to rip out something that makes little sense, only to find themselves hauled into the CTO's office to explain why they've gone against the client's wishes & be embarrassingly made to restore it in an emergency release.
Good recommendation. Many -- perhaps all -- developers would benefit from reading Clean Code, even if they don't agree with every word.
I tend to agree about comments. Expressive code shouldn't need endless comments. That said, there are times when the code can't tell the full story -- if it's doing something funky, or you want to explain your design decisions. In these cases, comments are definitely needed.
Yeah exactly. There are times when comments are needed. Thanks for the comment.