3 ms·

I think you're giving very bad advice. > On a basic level, comments should: inform, educate, outline and help others understand the sometimes complex routines

I think you're giving very bad advice. > On a basic level, comments should: inform, educate, outline and help others understand the sometimes complex routines and functions that we all create and often under an enormous amount of pressure. Take the time to simplify the complex routines, clean them up and make them readable and don't waste your precious time in writing "good comments". > Code can become complex, awkward, spaghetti-like and almost unfathomable at times. The solution for this is not "comment more". It's "clean up the mess". > At times, code comments can be worth more than the code itself. That doesn't make any sense. If the code has no value, you can remove it. > I've always strived to teach less experienced developers to comment well, efficiently and with a little humor/humour (where possible); Something that allows us to understand code quickly, appreciate the efforts of those before us and smile/grin at the complexity of a challenge. Please don't do that. Of course it's your code base, but usually it's best to find better venues to express your humor than code comments. Also: teach the junior developers to write clean code first. Comments too often are used as a bad device to fix code. A developer first writes a horrible mess of code and stops. He may then realize that perhaps no-one will understand it. But if we now teach them not to clean up the code but rather just "write some funny comments", do you think it's any better? I've seen too many code bases written with this attitude. The comments usually don't help at all, they distract the reader and they distract the author. It's too often useless noise. Many developers hide the comments from these code bases so that they can concentrate on what ACTUALLY is relevant: the code.

ptttr 8y ago
The worst part about comments is that they just add a cognitive load of reading and parsing extra lines of text. What if the underlying logic changes? Do I need to update the original witty comment as well? How do I know if the comment is still relevant? No compiler nor tests will tell me that and now I'm left with a task of parsing a language with much more degrees of freedom (English), without any support from the IDE. It becomes even harder in international teams.
majikandy 8y ago
Well said, I was cringing when I was reading the bad advice and you addressed the points very well. It is so frustrating to hear when someone thinks commenting more and adding humour is somehow cleaning up the code. But to then hear that they are teaching this to juniors just hurts so much. Simpler advice to juniors would be to read Clean Code by Robert C Martin, apply some of those techniques and then politely ignore “more experienced” developers who think writing humourous essays as code comments is a good thing. I’ve even heard phrases banded around like “the more comments the better” - I mean seriously WTF. I like the analogy of... When in an unfamiliar city, having no map at all is much better than a map that you have no idea whether you can trust or not. Code comments are absolutely that untrustworthy map, doesn’t matter how many code reviews or convoluted PR process takes place, you still need to read the code to know the truth so more effort making the code communicate is the key to maintainable code. Simple things like good variable names and grouping behaviour into functions at the same level of abstraction can completely negate the need for comments. Comments have their place, but should be the exception not the norm.
- pas 8y ago
  I disagree with nickharr's opinion on humor just as starkly as you, but agree with the need for comments very much. And his/her point still stands regardless of how much you name and group functions. There are concerns and aspects (design/engineering decisions become implementation details that might need rationale) that can't be presented efficiently that way. (Workarounds for issues benefit a lot from links to the relevant issue trackers, and so on.)
  - nickharr 8y ago
    Point taken, but my point wasn't about adding humor as some form of default - just something that's amusing to come across when you find it as a developer and where others have struggled/suffered. You are reading too much into it, but appreciate I wasn't clear enough in my initial description.

ptttr 8y ago

The worst part about comments is that they just add a cognitive load of reading and parsing extra lines of text. What if the underlying logic changes? Do I need to update the original witty comment as well? How do I know if the comment is still relevant? No compiler nor tests will tell me that and now I'm left with a task of parsing a language with much more degrees of freedom (English), without any support from the IDE. It becomes even harder in international teams.

majikandy 8y ago

Well said, I was cringing when I was reading the bad advice and you addressed the points very well. It is so frustrating to hear when someone thinks commenting more and adding humour is somehow cleaning up the code. But to then hear that they are teaching this to juniors just hurts so much. Simpler advice to juniors would be to read Clean Code by Robert C Martin, apply some of those techniques and then politely ignore “more experienced” developers who think writing humourous essays as code comments is a good thing. I’ve even heard phrases banded around like “the more comments the better” - I mean seriously WTF. I like the analogy of... When in an unfamiliar city, having no map at all is much better than a map that you have no idea whether you can trust or not. Code comments are absolutely that untrustworthy map, doesn’t matter how many code reviews or convoluted PR process takes place, you still need to read the code to know the truth so more effort making the code communicate is the key to maintainable code. Simple things like good variable names and grouping behaviour into functions at the same level of abstraction can completely negate the need for comments. Comments have their place, but should be the exception not the norm.

pas 8y ago
I disagree with nickharr's opinion on humor just as starkly as you, but agree with the need for comments very much. And his/her point still stands regardless of how much you name and group functions. There are concerns and aspects (design/engineering decisions become implementation details that might need rationale) that can't be presented efficiently that way. (Workarounds for issues benefit a lot from links to the relevant issue trackers, and so on.)
- nickharr 8y ago
  Point taken, but my point wasn't about adding humor as some form of default - just something that's amusing to come across when you find it as a developer and where others have struggled/suffered. You are reading too much into it, but appreciate I wasn't clear enough in my initial description.