Andy Culbertson: Added the article.

2019-02-22T05:48:04Z

Added the article.

New page

Comments and self-documentation are the two sides of the code clarity coin.

Code comments are one of the [http://www.hacker-dictionary.com/terms/holy-wars holy wars] of programming--everyone has a strongly held view and debates it vigorously. I basically agree with the views in these articles:

* [https://visualstudiomagazine.com/articles/2013/06/01/roc-rocks.aspx Why You Shouldn't Comment (or Document) Code - Visual Studio Magazine]
* [https://sourcemaking.com/refactoring/smells/comments Comments - Source Making]
* [https://www.pluralsight.com/blog/software-development/code-comments-dos-and-donts Code comments: A quick guide on when (and when not) to use them - Pluralsight]

That is, comments are a liability, so for the most part write them as little as possible, and update them when you update the code. Make your code as clear as you can (see the self-documentation section), and comment only to communicate what the code can't on its own, such as its purpose and the reasoning behind your choices in implementing it. If nothing else, comments can be a good indication of places that need refactoring.

I don't think it's necessary to stick to one procedure for commenting, but generally when I've commented more, it's because I've paused after a chunk of coding time, such as when I've finished a function. I code in paragraphs, sets of related lines separated by a blank line. In the commenting phase I reread the code I've just written and try to summarize or justify each paragraph, if needed. Stepping back from the code to state things in English sometimes leads to improvements in the code--refactoring or bug fixes.

Here are some in-depth discussions on making code self-documenting:

* [http://wiki.c2.com/?SelfDocumentingCode Self Documenting Code - WikiWikiWeb]
* [http://wiki.c2.com/?SystemMetaphor System Metaphor - WikiWikiWeb]
* [https://m.signalvnoise.com/hunting-for-great-names-in-programming-16f624c8fc03 Hunting for great names in programming - Signal v. Noise]

Every solution has its own problems. Self-documentation can go wrong too, and in some of the same ways comments can. For example, your function name doesn't have to have anything to do with its contents. Here are a bunch of tricks for wrecking your code's clarity:

* [http://mindprod.com/jgloss/unmain.html unmaintainable code - Java Glossary]

On the problem that documentation isn't executable, behavior-driven development might give us a partial solution. See the links in the test-driven development section above.

[[Category:Programming]]
[[Category:Essays]]
[[Category:Developing]]

Software Development/Comments - Revision history

Andy Culbertson: Added the article.