Here is the problem with the majority of comments I see in the wild.
They just repeat what the code is doing. And they are often wrong, because they are not functional, they don't cause compilation errors and they don't cause crashes and make tests fail, so errors in the comments tend to go unnoticed. It is so bad sometimes that I trained myself not to read comments as they can be deceptive.
Comments are a side channel, and IMHO, strictly a side channel. They can be used to express what can't be expressed in code. A common usage is to explain why you chose a solution over another.
I have absolutely no problem with "if" statements, I also think too much indirection is cancer. I have a problem with booleans parameters however. They tend to result in confusing and error prone calls like style(true, false, true), instead of something like style(ITALIC, NO_BOLD, UNDERLINE). In C/C++, I then use "switch" instead of "if". The advantage of "switch" is that the compiler warns you if you forgot a case, you also avoid to problem of accidentally reversing the condition. Make sure your compiler warns you of unintended tall through too.
That’s indeed a problem. However, writing no comments can also be a problem, so one has to find a compromise.
I think comments are helpful given these two criteria are met:
* The comment is concise.
* The comment reveals something that is not obvious in the code that follows immediately after.
It is then also easier to spot and fix outdated comments.
A typical problem that I have encountered with the “no comments” approach is that developers then have to name stuff. And naming stuff is hard. Writing a sentence is much easier. This can be a bigger issue than an outdated comment.
As an example, I just reviewed a code base and found a class named “CaptionSubtitles”. It had a comment, but that also suffered from a language gap. I think this is an issue that is widely overlooked. Code expresses semantics, so names matter. A comment can in this case at least hint at a concept or thought that the original author had in mind who of course left a couple of years ago.
Yeah, comments like what you describe should simply be removed on sight. I think they are most useful in describing domain-specific context around some logic, that may not be obvious by reading the code alone.
Comments
Here is the problem with the majority of comments I see in the wild.
They just repeat what the code is doing. And they are often wrong, because they are not functional, they don't cause compilation errors and they don't cause crashes and make tests fail, so errors in the comments tend to go unnoticed. It is so bad sometimes that I trained myself not to read comments as they can be deceptive.
Comments are a side channel, and IMHO, strictly a side channel. They can be used to express what can't be expressed in code. A common usage is to explain why you chose a solution over another.
I have absolutely no problem with "if" statements, I also think too much indirection is cancer. I have a problem with booleans parameters however. They tend to result in confusing and error prone calls like style(true, false, true), instead of something like style(ITALIC, NO_BOLD, UNDERLINE). In C/C++, I then use "switch" instead of "if". The advantage of "switch" is that the compiler warns you if you forgot a case, you also avoid to problem of accidentally reversing the condition. Make sure your compiler warns you of unintended tall through too.
That’s indeed a problem. However, writing no comments can also be a problem, so one has to find a compromise.
I think comments are helpful given these two criteria are met:
* The comment is concise.
* The comment reveals something that is not obvious in the code that follows immediately after.
It is then also easier to spot and fix outdated comments.
A typical problem that I have encountered with the “no comments” approach is that developers then have to name stuff. And naming stuff is hard. Writing a sentence is much easier. This can be a bigger issue than an outdated comment.
As an example, I just reviewed a code base and found a class named “CaptionSubtitles”. It had a comment, but that also suffered from a language gap. I think this is an issue that is widely overlooked. Code expresses semantics, so names matter. A comment can in this case at least hint at a concept or thought that the original author had in mind who of course left a couple of years ago.
Yeah, comments like what you describe should simply be removed on sight. I think they are most useful in describing domain-specific context around some logic, that may not be obvious by reading the code alone.