For the cases you mention a combination of package name, class name and method / function name could serve as a comment with the benefit of making sure any place referencing the code also "documents" why something is happening (tests for example, or callers of your methods).
This is not always possible, and in those cases I also strongly prefer well written, concise comments explaining what is going on and why, ideally with a link to a reference/source which explains the background.
I hope this doesn't sound snarky. But more often than not comments do date in my experience (and they don't handle refactoring well), while (compiler-known) names are handled as 1st class citizens by the current IDEs and thus are corrected and updated anywhere.
In code reviews we usually aim for "low comment" density, the implementer shouldn't explain what or why he was doing, the reviewer has to understand just from the code (as it would happen if she/he has to maintain it later on). The review is "not good" or even fails if the reviewer doesn't understand why and what is happening. The outcome will in most cases be an improved design, not more comments.
But those method names are still hard to relate to the business cases your customer requested. So you implemented something for some reason; your code and methods tell you what you implemented but not why... Why did you use a tree? I read your top level code and think ; dude, that would have been so much simpler and faster using a Wobble instead of a Tree! Then I try that and it turns out it has to be a Tree; you went through the same process, did not tell me why and I lost a day retrying. For instance.
(assuming, which you should always assume imho, that you left the company many years ago when this event occurs)
If I wrote an explanation then what would check that explanation? Maybe I write "we use a Tree instead of a Wobble because Wobble doesn't support the APIs we need". But then maybe when you come to work on it, it turns out that the current version of Wobble does support those APIs. Maybe it's actually better at them than Tree. Whereas if I have a unit test around Tree that exercises the kind operations that we need to do, then you can just try dropping Wobble in there and see for yourself whether it works or not.
This is not always possible, and in those cases I also strongly prefer well written, concise comments explaining what is going on and why, ideally with a link to a reference/source which explains the background.
Some examples of method names:
- generateTreeToAllowPartitioningOfItems(...)
- getMatchingRegularizationPenaltyForSpecialCaseX(...)
- getShortTermRedisProxyCache(...)
- createNewPrefilledTemplateObjectForXYZ(...)
I hope this doesn't sound snarky. But more often than not comments do date in my experience (and they don't handle refactoring well), while (compiler-known) names are handled as 1st class citizens by the current IDEs and thus are corrected and updated anywhere.
In code reviews we usually aim for "low comment" density, the implementer shouldn't explain what or why he was doing, the reviewer has to understand just from the code (as it would happen if she/he has to maintain it later on). The review is "not good" or even fails if the reviewer doesn't understand why and what is happening. The outcome will in most cases be an improved design, not more comments.