self-documenting code

{{Short description|Source code written to enable use by others without prior experience}}

In computer programming, self-documenting (or self-describing) source code and user interfaces follow naming conventions and structured programming conventions that enable use of the system without prior specific knowledge.

Objectives

Commonly stated objectives for self-documenting systems include:

Make source code easier to read and understand
Minimize the effort required to maintain or extend legacy systems
Reduce the need for users and developers of a system to consult secondary documentation sources such as code comments or software manuals
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 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.

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;

}

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.

References

{{Reflist|refs=

{{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}}

{{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]

{{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. […]}}

}}