I strongly believe that a comment is never wrong, unless outdated or misleading.
// The age of the user.intuserAge;
That's a comment that is neither outdated nor misleading but is quite useless. If we go by your rule, we'll be duplicating our code with a 1:1 comment; violating the DRY principle.
I'm not too sure about it violating DRY principle since the code itself and the comment serves for different purposes.
You could argue that the code is already doing the job of documentation. Would you say that you get the idea faster by reading something camelCase like userAge than a well-versed English sentence The age of the user.? In my case at least, it takes me some extra seconds without the comment.
I don't encourage this type of comments, but I don't see how it is damaging you either. Would you remove this type of comment if you find it in a program that you're working with?
You could argue that the code is already doing the job of documentation. Would you say that you get the idea faster by reading something camelCase like userAge than a well-versed English sentence The age of the user?
Yes, indeed. A 30 line function with 15 lines of logic + 15 lines of comments will take up more cognitive load compared to the one with 0-2 lines of comments and good naming/structure.
I don't encourage this type of comments, but I don't see how it is damaging you either.
It's clutter and noise, IMO.
Would you remove this type of comment if you find it in a program that you're working with?
In a collaborative scenario? It's a point of discussion with the one who committed the snippet, that's for sure.
Yes, indeed. A 30 line function with 15 lines of logic + 15 lines of comments will take up more cognitive load compared to the one with 0-2 lines of comments and good naming/structure.
Hmmm I think that I get your point now. When looking at a function for documentation I always read the comment and skip the code (unless debugging/reviewing it, in which the comments are helpful to understand the intended behavior), so I don't feel this cognitive load (this is just me though).
In a collaborative scenario? It's a point of discussion with the one who committed the snippet, that's for sure.
I'm not too sure if this is worth taking even 3 minutes from someone else's times to discuss whenever the comment was needed or not. You must be really feeling the clutter/noise to consider it a point of discussion.
Perhaps if one member of my team is writing this type of comments and he/she had done it several times, I'd take 5-10 minutes to speak with that person about it (I still wouldn't ask the person to remove the comments..).
I'm not too sure if this is worth taking even 3 minutes from someone else's times to discuss whenever the comment was needed or not.
Setting up standards is an important point for a development team. If the guy that writes comments like these have a reason for doing so, he should discuss it with the team for standardization.
I totally agree with John, I think comments add much clutter to code and you have to use them carefully. Writing self explanatory code is not an easy task so sometimes comments can cover it.
But eventually it is up to the team culture. If your team likes to comment so go ahead and just do it
That's a comment that is neither outdated nor misleading but is quite useless. If we go by your rule, we'll be duplicating our code with a 1:1 comment; violating the DRY principle.
Hey Alcher, thanks for the code sample.
I'm not too sure about it violating DRY principle since the code itself and the comment serves for different purposes.
You could argue that the code is already doing the job of documentation. Would you say that you get the idea faster by reading something camelCase like
userAgethan a well-versed English sentenceThe age of the user.? In my case at least, it takes me some extra seconds without the comment.I don't encourage this type of comments, but I don't see how it is damaging you either. Would you remove this type of comment if you find it in a program that you're working with?
Yes, indeed. A 30 line function with 15 lines of logic + 15 lines of comments will take up more cognitive load compared to the one with 0-2 lines of comments and good naming/structure.
It's clutter and noise, IMO.
In a collaborative scenario? It's a point of discussion with the one who committed the snippet, that's for sure.
Hmmm I think that I get your point now. When looking at a function for documentation I always read the comment and skip the code (unless debugging/reviewing it, in which the comments are helpful to understand the intended behavior), so I don't feel this cognitive load (this is just me though).
I'm not too sure if this is worth taking even 3 minutes from someone else's times to discuss whenever the comment was needed or not. You must be really feeling the clutter/noise to consider it a point of discussion.
Perhaps if one member of my team is writing this type of comments and he/she had done it several times, I'd take 5-10 minutes to speak with that person about it (I still wouldn't ask the person to remove the comments..).
Setting up standards is an important point for a development team. If the guy that writes comments like these have a reason for doing so, he should discuss it with the team for standardization.
I agree that setting up standards is very important, thanks for your thoughts.
I totally agree with John, I think comments add much clutter to code and you have to use them carefully. Writing self explanatory code is not an easy task so sometimes comments can cover it.
But eventually it is up to the team culture. If your team likes to comment so go ahead and just do it
If the comment really helps you in this case, why don't you make the code more like the comment?
That is the better way, in my opinion, since the comment is not necessary and therefore you cannot forget to change comment when the code changes.
"When you feel the need to write a comment, first try to refactor the code so that any comment becomes superflouus." - Martin Fowler
That's a good quote!