<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom" xml:lang="en">
	<id>https://www.thinkulum.net/w/index.php?action=history&amp;feed=atom&amp;title=Software_Development%2FComments</id>
	<title>Software Development/Comments - Revision history</title>
	<link rel="self" type="application/atom+xml" href="https://www.thinkulum.net/w/index.php?action=history&amp;feed=atom&amp;title=Software_Development%2FComments"/>
	<link rel="alternate" type="text/html" href="https://www.thinkulum.net/w/index.php?title=Software_Development/Comments&amp;action=history"/>
	<updated>2026-11-17T21:54:15Z</updated>
	<subtitle>Revision history for this page on the wiki</subtitle>
	<generator>MediaWiki 1.37.1</generator>
	<entry>
		<id>https://www.thinkulum.net/w/index.php?title=Software_Development/Comments&amp;diff=392&amp;oldid=prev</id>
		<title>Andy Culbertson: Added the article.</title>
		<link rel="alternate" type="text/html" href="https://www.thinkulum.net/w/index.php?title=Software_Development/Comments&amp;diff=392&amp;oldid=prev"/>
		<updated>2019-02-22T05:48:04Z</updated>

		<summary type="html">&lt;p&gt;Added the article.&lt;/p&gt;
&lt;p&gt;&lt;b&gt;New page&lt;/b&gt;&lt;/p&gt;&lt;div&gt;Comments and self-documentation are the two sides of the code clarity coin.&lt;br /&gt;
&lt;br /&gt;
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:&lt;br /&gt;
&lt;br /&gt;
* [https://visualstudiomagazine.com/articles/2013/06/01/roc-rocks.aspx Why You Shouldn&amp;#039;t Comment (or Document) Code - Visual Studio Magazine]&lt;br /&gt;
* [https://sourcemaking.com/refactoring/smells/comments Comments - Source Making]&lt;br /&gt;
* [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]&lt;br /&gt;
&lt;br /&gt;
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&amp;#039;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.&lt;br /&gt;
&lt;br /&gt;
I don&amp;#039;t think it&amp;#039;s necessary to stick to one procedure for commenting, but generally when I&amp;#039;ve commented more, it&amp;#039;s because I&amp;#039;ve paused after a chunk of coding time, such as when I&amp;#039;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&amp;#039;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.&lt;br /&gt;
&lt;br /&gt;
Here are some in-depth discussions on making code self-documenting:&lt;br /&gt;
&lt;br /&gt;
* [http://wiki.c2.com/?SelfDocumentingCode Self Documenting Code - WikiWikiWeb]&lt;br /&gt;
* [http://wiki.c2.com/?SystemMetaphor System Metaphor - WikiWikiWeb]&lt;br /&gt;
* [https://m.signalvnoise.com/hunting-for-great-names-in-programming-16f624c8fc03 Hunting for great names in programming - Signal v. Noise]&lt;br /&gt;
&lt;br /&gt;
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&amp;#039;t have to have anything to do with its contents. Here are a bunch of tricks for wrecking your code&amp;#039;s clarity:&lt;br /&gt;
&lt;br /&gt;
* [http://mindprod.com/jgloss/unmain.html unmaintainable code - Java Glossary]&lt;br /&gt;
&lt;br /&gt;
On the problem that documentation isn&amp;#039;t executable, behavior-driven development might give us a partial solution. See the links in the test-driven development section above.&lt;br /&gt;
&lt;br /&gt;
[[Category:Programming]]&lt;br /&gt;
[[Category:Essays]]&lt;br /&gt;
[[Category:Developing]]&lt;/div&gt;</summary>
		<author><name>Andy Culbertson</name></author>
	</entry>
</feed>