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.

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'.

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.

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.

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.

I can't agree with this enough. My advice is: when the reason for doing something is not self-explanatory, add a brief comment.

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).

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.

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

    # 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.

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.

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".

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.

No one wants to look through a lengthy git log to find the reason something was done to a particular block of code!

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.

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.

Half of the time, when I look at the git blame for a certain line, I get: 'whitespace-only change'

Isn't a short comment a much quicker method to get why something has been done that way instead of having to check git log? Also, if you rely on git log for that, don't commit messages become unnecessarily long and detailed?

Commits should be long and detailed, though the details for the commit log are for a different purpose. In the commit logs I want to know why the change was developed -- what issue it fixed, what feature request it implements. I want the code comments to explain the logic of a large chunk of code, at a higher level than just reading line by line.

no, that rarely happens. There are plugins where you can run git blame within your text editor by marking text. It is like you have a comment but without making the code more messy as it only shows with a "click".

Another point is that people tend to write awful comments anyway.

>Another point is that people tend to write awful comments anyway.

This. When we talk about stellar teams with stellar writers both in programming language and english, it seems nice to throw comment here and there. But when I look at what we do at work, I just... want to s{//.+$}{}, because comments there are A) misleading, B) senseless, C) grammatically awful, D) obsolete. Today almost everyone can be a programmer, but only few know how to explain things in short text at right place. You have to be writer to do that.

The best way to test a comment is to turn it into code and test it as code. Or, in more modern way, make a neural network that parses comments and check if these apply.

Any examples? That sounds like it might get awkward when it comes to reuse.

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.

Sounds like you learned how to code, but not how to engineer software.

Thats a bit much to suspect based on a single sentence don't you think?

I am sure there are environments where this would be super messy, but if you work in small teams in a given structure always following best practice and basic refactoring. 99.9% of the code gets pretty obvious in its use.

It's interesting what you say, because I sometimes don't know when a particular comment should go into code or commit message!

If you would work in the company i worked (e-gov in switzerland) comments are strongly discouraged (except as said if you do something stupid and you expect the reviewer to notice and give some inputs).

My rule is like: Make the code say what it does, if you have to explain why it does what it does do it in the commit message.