Self-documenting code

Conventions

Self-documenting code is ostensibly written using human-readable names, typically consisting of a phrase in a human language which reflects the symbol's meaning, such as article.numberOfWords or TryOpen. The code must also have a clear and clean structure so that a human reader can easily understand the algorithm used.

Practical considerations

There are certain practical considerations that influence whether and how well the objectives for a self-documenting system can be realized.

• uniformity of naming conventions
• consistency
• scope of the application and system requirements

Examples

Below is a very simple example of self-documenting C code, using naming conventions in place of explicit comments to make the logic of the code more obvious to human readers.

<span id="mwPQ"></span><span class="kt" id="mwPg">size_t</span><span class="w" id="mwPw"> </span><span class="nf" id="mwQA">count_alphabetic_chars</span><span class="p" id="mwQQ">(</span><span class="k" id="mwQg">const</span><span class="w" id="mwQw"> </span><span class="kt" id="mwRA">char</span><span class="w" id="mwRQ"> </span><span class="o" id="mwRg">*</span><span class="n" id="mwRw">text</span><span class="p" id="mwSA">)</span> <span class="p" id="mwSQ">{</span> <span class="w" id="mwSg"> </span><span class="k" id="mwSw">if</span><span class="w" id="mwTA"> </span><span class="p" id="mwTQ">(</span><span class="n" id="mwTg">text</span><span class="w" id="mwTw"> </span><span class="o" id="mwUA">==</span><span class="w" id="mwUQ"> </span><span class="nb" id="mwUg">NULL</span><span class="p" id="mwUw">)</span> <span class="w" id="mwVA"> </span><span class="k" id="mwVQ">return</span><span class="w" id="mwVg"> </span><span class="mi" id="mwVw">0</span><span class="p" id="mwWA">;</span> <span class="w" id="mwWQ"> </span><span class="kt" id="mwWg">size_t</span><span class="w" id="mwWw"> </span><span class="n" id="mwXA">count</span><span class="w" id="mwXQ"> </span><span class="o" id="mwXg">=</span><span class="w" id="mwXw"> </span><span class="mi" id="mwYA">0</span><span class="p" id="mwYQ">;</span> <span class="w" id="mwYg"> </span><span class="k" id="mwYw">while</span><span class="w" id="mwZA"> </span><span class="p" id="mwZQ">(</span><span class="o" id="mwZg">*</span><span class="n" id="mwZw">text</span><span class="w" id="mwaA"> </span><span class="o" id="mwaQ">!=</span><span class="w" id="mwag"> </span><span class="sc" id="mwaw">'\0'</span><span class="p" id="mwbA">)</span> <span class="w" id="mwbQ"> </span><span class="p" id="mwbg">{</span> <span class="w" id="mwbw"> </span><span class="k" id="mwcA">if</span><span class="w" id="mwcQ"> </span><span class="p" id="mwcg">(</span><span class="n" id="mwcw">is_alphabetic</span><span class="p" id="mwdA">(</span><span class="o" id="mwdQ">*</span><span class="n" id="mwdg">text</span><span class="p" id="mwdw">))</span> <span class="w" id="mweA"> </span><span class="n" id="mweQ">count</span><span class="o" id="mweg">++</span><span class="p" id="mwew">;</span> <span class="w" id="mwfA"> </span><span class="n" id="mwfQ">text</span><span class="o" id="mwfg">++</span><span class="p" id="mwfw">;</span> <span class="w" id="mwgA"> </span><span class="p" id="mwgQ">}</span> <span class="w" id="mwgg"> </span><span class="k" id="mwgw">return</span><span class="w" id="mwhA"> </span><span class="n" id="mwhQ">count</span><span class="p" id="mwhg">;</span> <span class="p" id="mwhw">}</span>

Criticism

Jef Raskin criticized the belief in "self-documenting" code by saying that code cannot explain the rationale behind why the program is being written or why it is implemented in such a way.