My strongly held opinion which is probably unpopular: code comments are a code smell, with very exceptional exceptions. Prose comments are almost immediately su

My strongly held opinion which is probably unpopular: code comments are a code smell, with very exceptional exceptions. Prose comments are almost immediately suspect, because they’re almost certainly not maintained alongside the code under comment (presume out of date). Prose comments which describe what something does almost always describe it worse than the code itself, and almost always suggest the code itself is too complex. Prose comments which describe why something was done the non-obvious way it was are potentially very useful, but still fall out of date too easily and should be used sparingly. Code comments that aid automation are better, but only if they’re reliably up to date too. More often than not, a type definition or a smaller function with a descriptive name and predictable properties/parameters serves the purpose of all of these cases much better than a comment would. And when I do write comments, my heuristic for whether it’s valuable is basically “is it longer than a sentence, and can it link to some other reference for future reading?” Secondarily, “did someone ask about this in review and we decided to leave something non-obvious intact?” Not perfect heuristics! But they’ve served me well, especially compared to trying to understand comments which don’t seem to make any sense when I encounter them.