Self-documenting code

Last updated

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. [1] In web development, self-documenting refers to a website that exposes the entire process of its creation through public documentation, and whose public documentation is part of the development process.[ citation needed ]

Contents

Objectives

Commonly stated objectives for self-documenting systems include:

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.

Examples

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

size_tcount_alphabetic_chars(constchar*text){if(text==NULL)return0;size_tcount=0;while(*text!='\0'){if(is_alphabetic(*text))count++;text++;}returncount;}

Criticism

Jef Raskin criticizes 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. [3]

See also

Related Research Articles

Computer programming is the process of designing and building an executable computer program to accomplish a specific computing result or to perform a specific task. Programming involves tasks such as: analysis, generating algorithms, profiling algorithms' accuracy and resource consumption, and the implementation of algorithms in a chosen programming language. The source code of a program is written in one or more languages that are intelligible to programmers, rather than machine code, which is directly executed by the central processing unit. The purpose of programming is to find a sequence of instructions that will automate the performance of a task on a computer, often for solving a given problem. Proficient programming thus often requires expertise in several different subjects, including knowledge of the application domain, specialized algorithms, and formal logic.

Literate programming

Literate programming is a programming paradigm introduced by Donald Knuth in which a computer program is given an explanation of its logic in a natural language, such as English, interspersed with snippets of macros and traditional source code, from which compilable source code can be generated. The approach is used in scientific computing and in data science routinely for reproducible research and open access purposes. Literate programming tools are used by millions of programmers today.

Quine (computing) Self-replicating program

A quine is a computer program which takes no input and produces a copy of its own source code as its only output. The standard terms for these programs in the computability theory and computer science literature are "self-replicating programs", "self-reproducing programs", and "self-copying programs".

Software documentation is written text or illustration that accompanies computer software or is embedded in the source code. The documentation either explains how the software operates or how to use it, and may mean different things to people in different roles.

In computing, source code is any collection of code, with or without comments, written using a human-readable programming language, usually as plain text. The source code of a program is specially designed to facilitate the work of computer programmers, who specify the actions to be performed by a computer mostly by writing source code. The source code is often transformed by an assembler or compiler into binary machine code that can be executed by the computer. The machine code might then be stored for execution at a later time. Alternatively, source code may be interpreted and thus immediately executed.

Jef Raskin

Jef Raskin was an American human–computer interface expert best known for conceiving and starting the Macintosh project at Apple in the late 1970s.

Syntax highlighting Tool of editors for programming, scripting, and markup

Syntax highlighting is a feature of text editors that are used for programming, scripting, or markup languages, such as HTML. The feature displays text, especially source code, in different colours and fonts according to the category of terms. This feature facilitates writing in a structured language such as a programming language or a markup language as both structures and syntax errors are visually distinct. This feature is also employed in many programming related contexts, either in the form of colorful books or online websites to make understanding code snippets easier for readers. Highlighting does not affect the meaning of the text itself; it is intended only for human readers.

Human-readable medium Representation of data or information that can be naturally read by humans

A human-readable medium or human-readable format is any encoding of data or information that can be naturally read by humans.

Code folding Tool of editors for programming, scripting and markup

Code folding or less commonly holophrasting is a feature of some text editors, source code editors, and IDEs that allows the user to selectively hide and display – "fold" – sections of a currently edited file as a part of routine edit operations. This allows the user to manage large amounts of text while viewing only those subsections of the text that are specifically relevant at any given time.

Ctags is a programming tool that generates an index file of names found in source and header files of various programming languages to aid code comprehension. Depending on the language, functions, variables, class members, macros and so on may be indexed. These tags allow definitions to be quickly and easily located by a text editor, a code search engine, or other utility. Alternatively, there is also an output mode that generates a cross reference file, listing information about various names found in a set of language files in human-readable form.

reStructuredText is a file format for textual data used primarily in the Python programming language community for technical documentation.

A random password generator is software program or hardware device that takes input from a random or pseudo-random number generator and automatically generates a password. Random passwords can be generated manually, using simple sources of randomness such as dice or coins, or they can be generated using a computer.

Archy is a software system whose user interface introduced a different approach for interacting with computers with respect to traditional graphical user interfaces. Designed by human-computer interface expert Jef Raskin, it embodies his ideas and established results about human-centered design described in his book The Humane Interface. These ideas include content persistence, modelessness, a nucleus with commands instead of applications, navigation using incremental text search, and a zooming user interface (ZUI). The system was being implemented at the Raskin Center for Humane Interfaces under Raskin's leadership. Since his death in February 2005 the project was continued by his team, which later shifted focus to the Ubiquity extension for the Firefox browser.

Markdown Plain text markup language

Markdown is a lightweight markup language for creating formatted text using a plain-text editor. John Gruber and Aaron Swartz created Markdown in 2004 as a markup language that is appealing to human readers in its source code form. Markdown is widely used in blogging, instant messaging, online forums, collaborative software, documentation pages, and readme files.

Noweb, stylised in lowercase as noweb, is a literate programming tool, created in 1989–1999 by Norman Ramsey, and designed to be simple, easily extensible and language independent.

AsciiDoc is a human-readable document format, semantically equivalent to DocBook XML, but using plain-text mark-up conventions. AsciiDoc documents can be created using any text editor and read “as-is”, or rendered to HTML or any other format supported by a DocBook tool-chain, i.e. PDF, TeX, Unix manpages, e-books, slide presentations, etc. Common file extensions for AsciiDoc files are txt and adoc.

Coding conventions are a set of guidelines for a specific programming language that recommend programming style, practices, and methods for each aspect of a program written in that language. These conventions usually cover file organization, indentation, comments, declarations, statements, white space, naming conventions, programming practices, programming principles, programming rules of thumb, architectural best practices, etc. These are guidelines for software structural quality. Software programmers are highly recommended to follow these guidelines to help improve the readability of their source code and make software maintenance easier. Coding conventions are only applicable to the human maintainers and peer reviewers of a software project. Conventions may be formalized in a documented set of rules that an entire team or company follows, or may be as informal as the habitual coding practices of an individual. Coding conventions are not enforced by compilers.

Comment (computer programming)

In computer programming, a comment is a programmer-readable explanation or annotation in the source code of a computer program. They are added with the purpose of making the source code easier for humans to understand, and are generally ignored by compilers and interpreters. The syntax of comments in various programming languages varies considerably.

JSDoc is a markup language used to annotate JavaScript source code files. Using comments containing JSDoc, programmers can add documentation describing the application programming interface of the code they're creating. This is then processed, by various tools, to produce documentation in accessible formats like HTML and Rich Text Format. The JSDoc specification is released under CC BY-SA 3.0, while its companion documentation generator and parser library is free software under the Apache License 2.0.

FLOW is an educational programming language designed by Jef Raskin and Jonathan (Jon) Collins, an undergraduate student in the UCSD Art Department, in 1970 and implemented on several minicomputers in the early 1970s. The goal of the language is to make it easy to explore algorithms through a highly interactive environment. The overall language is very similar in syntax and structure to the BASIC programming language, but has a number of changes in order to make typing code easier. Most notable among these was the concept of "typing amplification", in which short strings, often a single character, were expanded by the language into the complete "unamplified" source code. Modern integrated development environments and code-oriented text editors often include a similar feature, now normally referred to as autocomplete. The beginning programmer would first create a flow chart to solve the problem. Since the all of problems involved words the solution was intuitive. The flow chart would be translated into the flow programming language using a top-down, mechanical method.

References

  1. Schach, Stephen R. (2011). Object-Oriented and Classical Software Engineering (8 ed.). McGraw-Hill Professional. pp.  505–507. ISBN   978-0-07337618-9. OCLC   477254661.
  2. 1 2 3 4 5 Paul, Matthias R. (2002-04-09). "Re: [fd-dev] ANNOUNCE: CuteMouse 2.0 alpha 1". freedos-dev. Archived from the original on 2020-03-24. Retrieved 2020-03-24. […] 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. […]
  3. Raskin, Jef (2005-03-18). "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". ACM Queue . Development. ACM, Inc. 3 (2). Archived from the original on 2020-03-24. Retrieved 2019-12-22.

Further reading