Some problem domains are inherently complex and the code written for them needs documentation. Some are not but get complicated during the design process and perverted into abominations that wouldn't have required documentation if the design and source were more readable.
I'm inclined to say that if you name things obviously and avoid cutesy idioms (AOP/reflection magic, ridiculous object hierarchies, etc) that code can be quite grokkable with little documentation. Of course this falls apart once you start dealing with hundreds of microservices or decades of tech debt but such is life.
> code can be quite grokkable with little documentation
Indeed, the code _itself_ can often be understood from reading the code. Documentation is for everything _else_ - explanation of the choices made and motivations when picking a particular design (so that they can be re-evaluated when a redesign is considered), customer-facing onboarding guides, runbooks for how to carry out operational tasks, and so on.
This is quite true and one of the reasons I hate auto-doc comments. If a function tells me that an input is an integer there's no reason to repeat that information in the header above the function unless that information is then being parsed to produce a more readable form of documentation (i.e. as JavaDoc was originally used). Additionally I personally, though I am happy to concede that it may benefit some people, loathe "$documentId The ID of a Document" style comments. If you are adding more information above and beyond what is relevant from code - especially if that information relates to why you chose this approach over a different one - that is useful information.
Documentation in the form of project planning documents, SOWs, data diagrams etc... - that stuff is always quite valuable, especially since it comes with an understanding that it was valid at a certain point in time (and may no longer be valid) but belies underlying decisions in how things were built and why.
The only justification I can give to “$documentId - The ID of a document” style comments would be if they are alongside comments that actually give context.
If there are 5 parameters, and 3 of them are helped with a bit of context, then adding superfluous comments to the other two makes sense because that in itself is a piece of documentation (parameters needed for a function or class).
If all of your comments are like that though? Gross.
That’s the theory. In real life, code is written by teams with different levels of skills over multiple periods of time. Expressiveness is a really hard skill that take years to master and that few people have and that you can only learn by yourself.
> Expressiveness is a really hard skill that take years to master
It is worse than that. Being good at expressive, self-documenting code correlates with strong communication skills and empathy. So programmers who get good at it tend to increase the risk of managerial borgification.
In general, they tend to get snapped up by other corporate roles, either officially (which at least grants them the pay benefits associated with the role) or unofficially.
I know a lot of great coders who ended up doing anything but code because they were the technical people with communication skills.
When there's a complex bit of code, I expect to be able to `git blame` lookup the githash on GitHub and read the PR/issue description that should say what it's trying to achieve and how. I write PR descriptions expecting them to help years later.
I'm inclined to say that if you name things obviously and avoid cutesy idioms (AOP/reflection magic, ridiculous object hierarchies, etc) that code can be quite grokkable with little documentation. Of course this falls apart once you start dealing with hundreds of microservices or decades of tech debt but such is life.