5 ms·

Having spent 25+ years writing, viewing, commenting on and reviewing code in a multitude of languages, this is good stuff to see - regardless of the 'style' of

Having spent 25+ years writing, viewing, commenting on and reviewing code in a multitude of languages, this is good stuff to see - regardless of the 'style' of programming (or the language broadly-speaking). Stepping back and whilst we can all overlook it, good code comments can make an enormous difference in productivity - both for an individual, a team and indeed a business. It aids repository knowledge (something that is easily lost between current and prior teams/individuals), which shouldn't be mistaken for the intelligence of someone looking at code... I've spent far too much time personally and otherwise attempting to reverse-engineer code written by someone with no comments or explanation. At times, super experienced programmers/developers will take performance-enhancing shortcuts that the less-experienced don't understand; They'll compress routines and functions that are a result of their explicit knowledge of a language and/or domain but without explanation... 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. There are those that believe good code shouldn't need explanation and to some degree that's true, but you can't apply that brush to every codebase. Code can become complex, awkward, spaghetti-like and almost unfathomable at times. 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. Personally, I don't really care about the code/comment ratio - It's a complete red herring. At times, code comments can be worth more than the code itself. At other times, they just help you get your job done; quickly, efficiently, no fuss, just great code.

lmm 8y ago
> There are those that believe good code shouldn't need explanation and to some degree that's true, but you can't apply that brush to every codebase. Code can become complex, awkward, spaghetti-like and almost unfathomable at times. I have yet to find a codebase that couldn't be made clear as soon as a programmer actually put some effort into doing so. Far too often adding a comment is used as an excuse to give up on making the code readable before you've even started.
- pas 8y ago
  Well, you seem to be providing data against your own theory. Usually codebases are a mess, so were people commenting more on what's the goal then refactoring it would be easier. Software is very susceptible to the "perfect is the enemy of done" mantra. Software works as soon as it works for the first time. And then it gets a shipped. It's 1.0, even if it looks like a mess internally. Because IT development is expensive, there is rarely budget to go that extra mile (which is again usually would cost a lot more than the first few miles).
- xixixao 8y ago
  Here’s a great practice: 1. Write some piece of code 2. Now write a comment about it 3. Is the comment adding more information, making the code more clear? If Yes: Put that information into the code. Rename variables. Pull out code into subroutines. If No: Delete the comment. You’ll be amazed at how often this practice works. Doing it all the time will make your code more readable. We have a second, enforced practice at work, thanks to code review. The question in your head is simply: “Am I gonna get a comment about this at review time?” If yes, you gotta make the code clearer/simpler/better. Because you’ll have to answer and address the comment, and that’s just gonna slow you down more than if you just fix the problem now.
  - pas 8y ago
    There are concerns and aspects of software engineering that are important to document but don't sit well in code, but they become important when reading / maintaining that code. Design decisions (implementation details), specification details, other design or engineering constraints. And of course business modeling fundamentals and constraints. Sure, in theory, you can do everything in code, but I find that usually this trade off is taken, as there's no time/budget to go that 80% extra time. (Or however the Pareto curve looks for the actual problem. And usually it's not less than 80, but more.)
    - nickharr 8y ago
      I would never suggest documentation in code alone... Your point is very much noted, echoed and a hat-tip to you here. Yes, documentation is incredibly important, and it should be used as an driver/accompaniment along with comments.
asadkn 8y ago
Agreed. One of my pet peeves is JS projects. I am not sure why but the front-end developers refuse to add any comments at all. This trend, oddly enough, started with ES6. Pre-ES6, JSDoc style comments at least, were quite common. Just because some popular Javascript project doesn't have comments doesn't mean yours shouldn't. Straight-forward code may not need comments but most of these projects definitely need to explain why or how are things supposed to work or why things are done a certain way.
- kyberias 8y ago
  > Straight-forward code may not need comments but most of these projects definitely need to explain why or how are things supposed to work or why things are done a certain way. Code comments usually are not the best place to elaborate on "why things are done a certain way". One can also write documentation about the architecture, design etc.
  - pas 8y ago
    That'd be great, but rarely done. And usually there's a big impedance mismatch between the design document's level of detail and the level that'd be actually useful were someone trying to understand the actual code. (Hence comments seem to me to be the ideal place for documentation. Especially that they can be maintained right at the time the code changes.)
kyberias 8y ago
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.

lmm 8y ago

> There are those that believe good code shouldn't need explanation and to some degree that's true, but you can't apply that brush to every codebase. Code can become complex, awkward, spaghetti-like and almost unfathomable at times. I have yet to find a codebase that couldn't be made clear as soon as a programmer actually put some effort into doing so. Far too often adding a comment is used as an excuse to give up on making the code readable before you've even started.

pas 8y ago
Well, you seem to be providing data against your own theory. Usually codebases are a mess, so were people commenting more on what's the goal then refactoring it would be easier. Software is very susceptible to the "perfect is the enemy of done" mantra. Software works as soon as it works for the first time. And then it gets a shipped. It's 1.0, even if it looks like a mess internally. Because IT development is expensive, there is rarely budget to go that extra mile (which is again usually would cost a lot more than the first few miles).
xixixao 8y ago
Here’s a great practice: 1. Write some piece of code 2. Now write a comment about it 3. Is the comment adding more information, making the code more clear? If Yes: Put that information into the code. Rename variables. Pull out code into subroutines. If No: Delete the comment. You’ll be amazed at how often this practice works. Doing it all the time will make your code more readable. We have a second, enforced practice at work, thanks to code review. The question in your head is simply: “Am I gonna get a comment about this at review time?” If yes, you gotta make the code clearer/simpler/better. Because you’ll have to answer and address the comment, and that’s just gonna slow you down more than if you just fix the problem now.
- pas 8y ago
  There are concerns and aspects of software engineering that are important to document but don't sit well in code, but they become important when reading / maintaining that code. Design decisions (implementation details), specification details, other design or engineering constraints. And of course business modeling fundamentals and constraints. Sure, in theory, you can do everything in code, but I find that usually this trade off is taken, as there's no time/budget to go that 80% extra time. (Or however the Pareto curve looks for the actual problem. And usually it's not less than 80, but more.)
  - nickharr 8y ago
    I would never suggest documentation in code alone... Your point is very much noted, echoed and a hat-tip to you here. Yes, documentation is incredibly important, and it should be used as an driver/accompaniment along with comments.

asadkn 8y ago

Agreed. One of my pet peeves is JS projects. I am not sure why but the front-end developers refuse to add any comments at all. This trend, oddly enough, started with ES6. Pre-ES6, JSDoc style comments at least, were quite common. Just because some popular Javascript project doesn't have comments doesn't mean yours shouldn't. Straight-forward code may not need comments but most of these projects definitely need to explain why or how are things supposed to work or why things are done a certain way.

kyberias 8y ago
> Straight-forward code may not need comments but most of these projects definitely need to explain why or how are things supposed to work or why things are done a certain way. Code comments usually are not the best place to elaborate on "why things are done a certain way". One can also write documentation about the architecture, design etc.
- pas 8y ago
  That'd be great, but rarely done. And usually there's a big impedance mismatch between the design document's level of detail and the level that'd be actually useful were someone trying to understand the actual code. (Hence comments seem to me to be the ideal place for documentation. Especially that they can be maintained right at the time the code changes.)

kyberias 8y ago

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.