Although this is all my opinion on the topic only. I’m with @mtest . No code comments is a code-smell, too many comments is a code-pong. We seem to be talking about documentation as well as code readability here, but I’ll moan about the latter first to inform on the former.
I’ve been a coder for so long that I once had to double take when I spotted a duplicate semicolon in someone’s code from 5 meters away from the screen; too many comments break the code flow you see. And for me, the layout and code style are more important than code comments. Code has shape. Because good code is beautiful code, indentation and all, after a while actually invoke the pattern of the code fragment in the reader. Code that flows is quicker to read and grasp.
I do have 2 magic code look bullets, which I’ve not changed for a dozen years:
- Naming of things
- Strategic comments
Long code blocks are a code smell, they slow code comprehension and hide branch complexity, in much the same way that long comment blocks break your reader’s train of thought. Sometimes that reader will be you 10 years later. Try not to mix code and comment blocks, every function should fit into one screen, 30 lines max. (Remember data is not code.) Long functions can even tend to have more comments in them, ask yourself why.
Code never lies. Cleanly written code is very easy to read; code with big comment blocks is often there to explain code that the coder was hesitant about and that will invariably reflect in the code smell. This is where strategic comments come in. Strategic comments are about commenting to explain why you adopted a specific strategy .Your code strategy should be obvious to a reader anyway if you are following indentation and style rules, patterns like loops for searches, filters, builders and other patterns should all start to look like their kin if everyone codes neatly. You will be able to read clean code almost like spotting the girl in the red dress in the Matrix. The strategic comment is how you tell the reader who you chose a specific pattern - often it’s because of an externality like a API you consume that is either undocumented or behaves in an unexpected way. Never ever document “the code”, a comment on “the code” has that danger of miss-leading someone later when the code fragment get’s copy-pasted.
Naming of things is super important, if you name a function according to some set rules… just look at the language library that you use, you know what those functions do without reading their documentation don’t you? That’s because the functions are well chosen names, and since you have to be sure to break long functions into shorter ones where possible to satisfy DRY Don't repeat yourself - Wikipedia you will end up with more smaller functions, so come up with naming conventions that work. Pro Hint, functions with 2 verbs or two objects in them are often evil, because they break LISKOV Liskov substitution principle - Wikipedia which can even be applied not just to objects but also to methods or other encapsulations of a behaviour.
Basically if my code follows patterns and rules, it’s like a highway where all the road signs have an easy to grasp layout and I can move quickly from place to place. In the end I want comments in 2 places:
- Helping people use the code indexing tool by including a tooltip sized doc-comment to go with each function when I hover over it.
- When I’m telling the reader about an unexpected behaviour like a zero/nonzero based index for example.