In computer programming

Computer programming

Computer programming is the process of designing, writing, testing, debugging, and maintaining the source code of computer programs. This source code is written in one or more programming languages. The purpose of programming is to create a program that performs specific operations or exhibits a...

, self-documenting (or self-describing) is a common descriptor for source code

Source code

In computer science, source code is text written using the format and syntax of the programming language that it is being written in. Such a language is specially designed to facilitate the work of computer programmers, who specify the actions to be performed by a computer mostly by writing source...

 that follows certain loosely-defined conventions for naming

Naming conventions (programming)

In computer programming, a naming convention is a set of rules for choosing the character sequence to be used for identifiers which denote variables, types and functions etc...

 and structure

Structured programming

Structured programming is a programming paradigm aimed on improving the clarity, quality, and development time of a computer program by making extensive use of subroutines, block structures and for and while loops - in contrast to using simple tests and jumps such as the goto statement which could...

. These conventions are intended to enable developers, users, and maintainers of a system to use it effectively without requiring previous knowledge of its specification, design, or behavior.

Overview

The concept of self-description

Indirect self-reference

Indirect self-reference describes an object referring to itself indirectly.For example, define the function f such that f = "x". Any function passed as an argument to f is invoked with itself as an argument, and thus in any use of that argument is indirectly referring to itself.This example is...

 is not exclusively a property of certain kinds of source code. This concept has application to several areas in computer science

Computer science

Computer science or computing science is the study of the theoretical foundations of information and computation and of practical techniques for their implementation and application in computer systems...

, notably in computational linguistics

Computational linguistics

Computational linguistics is an interdisciplinary field dealing with the statistical or rule-based modeling of natural language from a computational perspective....

 and formal language theory. Additionally, self-describing systems may involve other areas in computing such as application design

Joint application design

Joint application design is a process used in the prototyping life cycle area of the Dynamic Systems Development Method to collect business requirements while developing new information systems for a company...

 and user interface

User interface

The user interface, in the industrial design field of human–machine interaction, is the space where interaction between humans and machines occurs. The goal of interaction between a human and a machine at the user interface is effective operation and control of the machine, and feedback from the...

s. Nevertheless, "self-documenting" is a term commonly used to designate a particular style of writing applied to source code for programming language

Programming language

A programming language is an artificial language designed to communicate instructions to a machine, particularly a computer. Programming languages can be used to create programs that control the behavior of a machine and/or to express algorithms precisely....

s, markup language

Markup language

A markup language is a modern system for annotating a text in a way that is syntactically distinguishable from that text. The idea and terminology evolved from the "marking up" of manuscripts, i.e. the revision instructions by editors, traditionally written with a blue pencil on authors' manuscripts...

s, and the like.

The designation of "self-documenting code" is often applied in a general sense, and not thoroughly defined according to a rigorous and exacting standard. Nevertheless, there are certain objectives, conventions, and practical considerations that usually apply when users of a system refer to this concept.

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; and
• facilitate automation
  Automation
  Automation is the use of control systems and information technologies to reduce the need for human work in the production of goods and services. In the scope of industrialization, automation is a step beyond mechanization...
  
   through self-contained Knowledge representation
  Knowledge representation
  Knowledge representation is an area of artificial intelligence research aimed at representing knowledge in symbols to facilitate inferencing from those knowledge elements, creating new elements of knowledge...
  
  .

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 numberOfWordsInThisArticle 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

External links

• Jef Raskin
  Jef Raskin
  Jef Raskin was an American human-computer interface expert best known for starting the Macintosh project for Apple in the late 1970s.-Early years and education:...
  
   on Self-documenting code: http://acmqueue.com/modules.php?name=Content&pa=showpage&pid=290&page=1.
• Steve McConnell
  Steve McConnell
  Steven C. McConnell is an author of many software engineering textbooks including Code Complete, Rapid Development, and Software Estimation...
  
  's High Quality Routines checklist in his book Code Complete
  Code Complete
  Code Complete is a software development book, written by Steve McConnell and published in 1993 by Microsoft Press, urging developers to get past code and fix programming and the "big design up front" waterfall model...
  
  helps to facilitate the creation of self-documenting code.