6 ms·

I'm a junior/trainee developer and I was advised that comments should explain why something is happening, not what is happening. The what should be self explana

I'm a junior/trainee developer and I was advised that comments should explain why something is happening, not what is happening. The what should be self explanatory by reading the code, but knowing why something is being done is useful when you, or someone else, has to look at it again in the future.

ed312 10y ago
This is the advice I give the junior devs I mentor. Write your code clearly and for other developers to read (yes that one-liner is clever, but refactor it so someone who just worked a 14 emergency deployment can understand it). Comments are for the why - quirky business rules, environment-specific issues, explaining an algorithm. Etc.
- madeofpalk 10y ago
  And a comment explaining why is especially useful when the code is a bit more dense and hard to follow - which is unavoidable at times. IMHO, your default mode should be to not to comment because you should instead focus on 'code as comments' - the code should be easy enough to read that it explains itself. Occasionally (for the reasons you pointed out) you need to fall back to english prose to explain those 'whys'.
  - Xylakant 10y ago
    on top of that the why can extend as to why this specific implementation route was chosen. Some algorithms are less efficient in a general case, but may be much more suitable to the specific case at hand. Things that were tried and proven not to work even though they seem beneficial at first glance.
  - wangchow 10y ago
    I think this is one of those things that is more about wisdom than anything else. You get a sense of what to comment over time and experience. Typically following language best-practices is ideal (pydoc, godoc, Javadoc, etc) so you can get easily-generated documentation for free. Following the standards will make any custom APIs consistent with the standard library API docs. The most important thing though is to ask for peer review on the code. When you are writing code (just like regular language) it will make sense to you regardless of comments or proper variable names. Have someone else read it and tell you what the confusing bits are. If there is no one to do that because you're a lone wolf, then step away from the work for a couple days and play golf or something. Then come back, read the code, and ask if it could be more clear. Then either change variable names or add comments for clarification.
- hliyan 10y ago
  I can't agree with this enough. My advice is: when the reason for doing something is not self-explanatory, add a brief comment.
- libc 10y ago
  Some high level "What" comments are useful though even if just for yourself, especially for code that can't be easily broken down into modular units. Even if the code itself is very clean, it's still faster to read that one line comment which summarizes it succinctly in plain English.
herbst 10y ago
I learned to code in a way that the variable and function names also would tell you the why. And otherwise the git log is your friend. Tl:dr; i only do comments to excuse really stupid code.
- sehr 10y ago
  Any examples? That sounds like it might get awkward when it comes to reuse.
  - herbst 10y ago
    Given we are a small team and know each others typical structures. It also helps that i only did this in a MVC environment, so structure was given mostly. I dont want to link to company applications honestly, and my personal ones are way to messy in terms of inline documentation anyway.
- hellofunk 10y ago
  No one wants to look through a lengthy git log to find the reason something was done to a particular block of code!
  - mattferderer 10y ago
    Visual Studio Pro & up has a great feature that puts a tiny snippet of text above each class & method that says the last author, how many authors & how many changes have been done on that specific class or method. You can hover over this text and see a box with a scroll bar that shows you the commits & comments that changed the class or method. I'm not sure if any other IDE or editors have this but I really love this feature as a method of documentation. I'm not saying it is the best method or the only method one should use, just a useful method that I wish more IDEs & editors had.
  - herbst 10y ago
    I assume every damn editor out there has a plugin that makes this a complete non issue. I spend most of my time in a terminal anyway and know my way around it, i prefer it by far to comments, also because of the metadata like dates and authors which rarely is found in comments.
crdoconnor 10y ago
This is the main reason. I also find a few other instances where it's useful: * Calling confusing 3rd party APIs - sure, maybe all your code is self-explanatory but your code probably has to talk to somebody else's code and theirs won't necessarily be so self explanatory. * Links to wiki pages and tickets. * As a stepping stone to cleaning up technical debt you might want to explain what is going on before refactoring the code into something more self-explanatry. * Adding context to an otherwise contextless module. * If somebody asked a question in a pull request based upon the code (if the reviewer didn't understand, it often needs a bit more explanation).
aidos 10y ago
Let's all post a sample comment! # we leave the existing pattern alone if it's the same # this is a performance optimisation to save us rerunning the # searches and cc resolution again
- zaphar 10y ago
  # NOTE(coderguy): Calling this method before calling # Init will result in a runtime error. I use comments to make people aware of invariants the code expects that aren't necessarily obvious from reading that code.
  - tempodox 10y ago
    If possible, document invariants as part of the code, not as a comment. Make it as hard as possible to misuse the thing. People not only don't read manuals, they also don't read comments. Which isn't to say you shouldn't comment your code.
    - aidos 10y ago
      I wouldn't use a comment in that situation either - I don't think a comment hurts, but I'd rather the code failed in an obvious way if I tried to use it incorrectly. My comments are generally along the lines of "so you're here because you need to change something? here's what you need to know", rather than "this is how you use this thing".
wruza 10y ago
It is also sometimes useful to determine places that should be commented not only from structure perspective, but also from call-stack. You can save few minutes yourself by explaining how this innocent assignment influences behavior several levels down there and vice versa, and that it was planned.

ed312 10y ago

This is the advice I give the junior devs I mentor. Write your code clearly and for other developers to read (yes that one-liner is clever, but refactor it so someone who just worked a 14 emergency deployment can understand it). Comments are for the why - quirky business rules, environment-specific issues, explaining an algorithm. Etc.

madeofpalk 10y ago
And a comment explaining why is especially useful when the code is a bit more dense and hard to follow - which is unavoidable at times. IMHO, your default mode should be to not to comment because you should instead focus on 'code as comments' - the code should be easy enough to read that it explains itself. Occasionally (for the reasons you pointed out) you need to fall back to english prose to explain those 'whys'.
- Xylakant 10y ago
  on top of that the why can extend as to why this specific implementation route was chosen. Some algorithms are less efficient in a general case, but may be much more suitable to the specific case at hand. Things that were tried and proven not to work even though they seem beneficial at first glance.
- wangchow 10y ago
  I think this is one of those things that is more about wisdom than anything else. You get a sense of what to comment over time and experience. Typically following language best-practices is ideal (pydoc, godoc, Javadoc, etc) so you can get easily-generated documentation for free. Following the standards will make any custom APIs consistent with the standard library API docs. The most important thing though is to ask for peer review on the code. When you are writing code (just like regular language) it will make sense to you regardless of comments or proper variable names. Have someone else read it and tell you what the confusing bits are. If there is no one to do that because you're a lone wolf, then step away from the work for a couple days and play golf or something. Then come back, read the code, and ask if it could be more clear. Then either change variable names or add comments for clarification.
hliyan 10y ago
I can't agree with this enough. My advice is: when the reason for doing something is not self-explanatory, add a brief comment.
libc 10y ago
Some high level "What" comments are useful though even if just for yourself, especially for code that can't be easily broken down into modular units. Even if the code itself is very clean, it's still faster to read that one line comment which summarizes it succinctly in plain English.

herbst 10y ago

I learned to code in a way that the variable and function names also would tell you the why. And otherwise the git log is your friend. Tl:dr; i only do comments to excuse really stupid code.

sehr 10y ago
Any examples? That sounds like it might get awkward when it comes to reuse.
- herbst 10y ago
  Given we are a small team and know each others typical structures. It also helps that i only did this in a MVC environment, so structure was given mostly. I dont want to link to company applications honestly, and my personal ones are way to messy in terms of inline documentation anyway.
hellofunk 10y ago
No one wants to look through a lengthy git log to find the reason something was done to a particular block of code!
- mattferderer 10y ago
  Visual Studio Pro & up has a great feature that puts a tiny snippet of text above each class & method that says the last author, how many authors & how many changes have been done on that specific class or method. You can hover over this text and see a box with a scroll bar that shows you the commits & comments that changed the class or method. I'm not sure if any other IDE or editors have this but I really love this feature as a method of documentation. I'm not saying it is the best method or the only method one should use, just a useful method that I wish more IDEs & editors had.
- herbst 10y ago
  I assume every damn editor out there has a plugin that makes this a complete non issue. I spend most of my time in a terminal anyway and know my way around it, i prefer it by far to comments, also because of the metadata like dates and authors which rarely is found in comments.

crdoconnor 10y ago

This is the main reason. I also find a few other instances where it's useful: * Calling confusing 3rd party APIs - sure, maybe all your code is self-explanatory but your code probably has to talk to somebody else's code and theirs won't necessarily be so self explanatory. * Links to wiki pages and tickets. * As a stepping stone to cleaning up technical debt you might want to explain what is going on before refactoring the code into something more self-explanatry. * Adding context to an otherwise contextless module. * If somebody asked a question in a pull request based upon the code (if the reviewer didn't understand, it often needs a bit more explanation).

aidos 10y ago

Let's all post a sample comment! # we leave the existing pattern alone if it's the same # this is a performance optimisation to save us rerunning the # searches and cc resolution again

zaphar 10y ago
# NOTE(coderguy): Calling this method before calling # Init will result in a runtime error. I use comments to make people aware of invariants the code expects that aren't necessarily obvious from reading that code.
- tempodox 10y ago
  If possible, document invariants as part of the code, not as a comment. Make it as hard as possible to misuse the thing. People not only don't read manuals, they also don't read comments. Which isn't to say you shouldn't comment your code.
  - aidos 10y ago
    I wouldn't use a comment in that situation either - I don't think a comment hurts, but I'd rather the code failed in an obvious way if I tried to use it incorrectly. My comments are generally along the lines of "so you're here because you need to change something? here's what you need to know", rather than "this is how you use this thing".

wruza 10y ago

It is also sometimes useful to determine places that should be commented not only from structure perspective, but also from call-stack. You can save few minutes yourself by explaining how this innocent assignment influences behavior several levels down there and vice versa, and that it was planned.