204.107.153.65: Removed an uncited claim from 7 years ago. The usage described doesn’t align with the rest of the article, and I’ve never encountered it used that way.

2025-04-16T18:31:42Z

Removed an uncited claim from 7 years ago. The usage described doesn’t align with the rest of the article, and I’ve never encountered it used that way.

New page

{{Short description|Source code written to enable use by others without prior experience}}
{{Refimprove|date=March 2020}}
{{Use dmy dates|date=March 2020|cs1-dates=y}}
In [[computer programming]], '''self-documenting''' (or '''self-describing''') [[source code]] and [[user interface]]s follow [[naming conventions (programming)|naming conventions]] and [[structured programming]] conventions that enable use of the system without prior specific knowledge.<ref name="Schach_2011"/>

==Objectives==
Commonly stated objectives for self-documenting systems include:

* Make source code easier to read and understand<ref name="Paul_2002_Symbols"/>
* Minimize the effort required to maintain or extend legacy systems<ref name="Paul_2002_Symbols"/>
* Reduce the need for users and developers of a system to consult secondary documentation sources such as [[Comment (computer programming)|code comments]] or [[software manual]]s<ref name="Paul_2002_Symbols"/>
* Facilitate [[automation]] through self-contained [[knowledge representation]]

==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 convention (programming)|naming conventions]]<ref name="Paul_2002_Symbols"/>
* consistency<ref name="Paul_2002_Symbols"/>
* scope of the application and [[system requirements]]

==Examples==
Below is a very simple example of self-documenting [[C (programming language) | C]] code, using naming conventions in place of explicit comments to make the logic of the code more obvious to human readers.

<syntaxhighlight lang="c">
size_t count_alphabetic_chars(const char *text)
{
if (text == NULL)
return 0;

size_t count = 0;

while (*text != '\0')
{
if (is_alphabetic(*text))
count++;
text++;
}

return count;
}
</syntaxhighlight>

== 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.<ref name="Raskin_2005"/>

==See also==
* [[Autological word]]
* [[Code readability]]
* [[Comment (computer programming)]]
* [[Controlled natural language]]
* [[Literate programming]]
* [[Natural language programming]]

==References==
{{Reflist|refs=
<ref name="Schach_2011">{{cite book |first=Stephen R. |last=Schach |title=Object-Oriented and Classical Software Engineering |url=https://archive.org/details/objectorientedcl00scha_416 |url-access=limited |edition=8 |publisher=[[McGraw-Hill Professional]] |date=2011 |pages=[https://archive.org/details/objectorientedcl00scha_416/page/n525 505]–507 |isbn=978-0-07337618-9 |oclc=477254661}}</ref>
<ref name="Raskin_2005">{{cite journal |author-first=Jef |author-last=Raskin |author-link=Jef Raskin |title=Comments Are More Important Than Code - The thorough use of internal documentation is one of the most-overlooked ways of improving software quality and speeding implementation. |series=Development |date=2005-03-18 |volume=3 |issue=2 |journal=[[ACM Queue]] |publisher=[[ACM, Inc.]] |url=https://queue.acm.org/detail.cfm?id=1053354 |access-date=2019-12-22 |url-status=live |archive-url=https://web.archive.org/web/20200324185056/https://queue.acm.org/detail.cfm?id=1053354 |archive-date=2020-03-24}} [https://web.archive.org/web/20050505065105/http://acmqueue.com/modules.php?name=Content&pa=showpage&pid=290&page=1][https://dl.acm.org/ft_gateway.cfm?id=1053354&ftid=300937&dwn=1]</ref>
<ref name="Paul_2002_Symbols">{{cite web |title=Re: [fd-dev] ANNOUNCE: CuteMouse 2.0 alpha 1 |author-first=Matthias R. |author-last=Paul |work=freedos-dev |date=2002-04-09 |url=https://marc.info/?l=freedos-dev&m=101832534205646&w=2 |access-date=2020-03-24 |url-status=live |archive-url=https://web.archive.org/web/20200324184426/https://marc.info/?l=freedos-dev&m=101832534205646&w=2 |archive-date=2020-03-24 |quote=[…] almost any numeric value in source code should be replaced by a corresponding symbol. This would greatly improve the self-explanatory aspect of source code and significantly ease maintenance of the code in the long run, as it would enable one to search for symbols to find relations between different excerpts of the code. […]}}</ref>
}}

==Further reading==
* {{cite book |author-first=Steve |author-last=McConnell |author-link=Steve McConnell |chapter=High Quality Routines checklist |title=Code Complete |title-link=Code Complete |chapter-url=http://cc2e.com/Page.aspx?hid=218}}

[[Category:Computer programming]]
[[Category:Software documentation]]

{{Compu-lang-stub}}

Self-documenting code - Revision history

204.107.153.65: Removed an uncited claim from 7 years ago. The usage described doesn’t align with the rest of the article, and I’ve never encountered it used that way.