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'.
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.
* 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).
# 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.
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".
Tl:dr; i only do comments to excuse really stupid code.
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.
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.
I dont want to link to company applications honestly, and my personal ones are way to messy in terms of inline documentation anyway.
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.
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.