If your code is unreadable, what makes you think your comments will be more will help?
In my experience, the greatest technical debt is accumulated by developers in too much of a hurry or too lazy to write code well. The irony is that their peers often can be heard saying things like, “Steve’s code is so good, no one can understand it.” That’s not how this works.
Good complex code is broken down into easy to read segments, which are commented briefly to describe why the code does what it does in each segment. These segments are grouped into larger abstractions. This is very similar to how a large book is written: sentences, paragraphs, sections, chapters, parts, volumes. Alternatively, you could just throw a jumble of notes containing the same information into a notebook, but no one will be able to understand it. Don’t do that with your code either.
Copyright © 2016 Sterling Hanenkamp.