View source for Wiki143:Manual of Style/Computer science

{{Redirect|WP:CODE|information about MediaWiki markup|Help:Wiki markup}}
{{Redirect|MOS:COMP|a former proposal that did not gain consensus|Wikipedia:Manual of Style/Computing (failed proposal)}}
{{MoS guideline|MOS:CS|MOS:COMPSCI}}
{{Style}}

This manual contains some suggestions which aim to contribute towards writing clear, pleasant looking, and hopefully interesting '''computer science''' articles. This guide is a complement to the general [[Wikipedia:Manual of Style|Manual of Style]].

== Suggested structure of a computer science article ==

Probably the hardest part of writing any technical article is the difficulty of addressing the level of technical knowledge on the part of the reader. A general approach is to start simple, and then move toward more formal and technical statements as the article proceeds. The following structure is merely recommended; editorial discretion and consensus might find an alternative structure more appropriate for some subjects.

=== Article introduction===
The article should start with an [[Wikipedia:Manual of Style/Lead section#Length|''lead section'' of length appropriate to the article content]], which describes the subject in general terms and properly summarizes the article. This opening material should give the casual reader a quick understanding of the concept. Name the field(s) of computer science this concept belongs to and describe the context in which the term is used. [[Wikipedia:Manual of Style/Lead section#Format of the first sentence|Write the '''article title''' and any alternative names in bold]]. Include the historical motivation, provide some names and dates, etc. Here is an example:

{{blockquote|1=In [[computer science]], '''communicating sequential processes''' ('''CSP''') is a [[formal language]] for describing [[pattern]]s of interaction in [[concurrent systems]]. It is a member of the family of mathematical theories of concurrency known as process algebras, or [[process calculus|process calculi]], based on [[message passing]] via [[Channel (programming)|channels]]. CSP was highly influential in the design of the [[occam (programming language)|occam]] programming language and also influenced the design of programming languages such as [[Limbo (programming language)|Limbo]], [[RaftLib]], [[Erlang (programming language)|Erlang]], [[Go (programming language)|Go]], [[Crystal (programming language)|Crystal]], and [[Clojure]]'s core.async. CSP was first described in a 1978 article by [[Tony Hoare]], but has since evolved substantially. CSP has been practically applied in industry as a tool for [[formal specification|specifying and verifying]] the concurrent aspects of a variety of different systems, such as the T9000 [[Transputer]], as well as a secure ecommerce system. The theory of CSP itself is also still the subject of active research, including work to increase its range of practical applicability (e.g., increasing the scale of the systems that can be tractably analyzed).}}

=== Background and application ===
{{Anchor|Overview and motivation|reason=Old, confusing section name; may have incoming links.}}
It is a good idea to begin the main part of the article with an informal introduction, commonly titled "Background" though "Overview" has also been used, that gives the non-technical reader a basic understanding of the fundamental concepts of the topic being presented. If the concept in question is somewhat theoretical, it is helpful to describe its {{em|purpose}} or {{em|applied use(s)}} toward the top of the article, either concisely in the lead section or in a post-lead introductory section. It is also useful to have some representative {{em|examples}}, which could serve both to expand on the concept in question and to provide some context as to {{em|why}} one might want to use that concept. 

A picture is a great way of bringing a point home, and often it could even precede the technical discussion of a concept. [[WP:How to create graphs for Wikipedia articles]] has some hints on how to create graphs and other pictures, and how to include them in articles.

If not included in the introductory material, a section about the {{em|history}} of the concept is often useful and can provide additional insight. This often forms its own "History" section.

=== Structuring different kinds of articles ===
Computer science is a broad field which encompasses a number of different kinds of ideas. The structure of the main part of an article will vary with the type of article. Here are some general guidelines for structuring a few different classes of computer science articles. Where possible, these guidelines include one or two examples of a "good" article, ''i.e.'' an article demonstrates the style we're aiming for in that particular class of article. Always keep in mind that these are ''guidelines'', not hard-and-fast rules: some articles will need to deviate from this structure; some articles will be hard to classify; some won't fit into these classifications at all. Use common sense in applying these guidelines.

==== Algorithms and data structures ====
An article on an algorithm should generally consist of:
# A description of the algorithm (including pseudocode)
# A formal discussion of the algorithm's time and space complexity
# A discussion of any implementation and performance issues

A good example is [[binary search algorithm]], a [[Wikipedia:Featured articles|featured article]].

An article on a data structure should consist of:
# A description of the structure, and any operations that can be performed on the structure 
# An overview of the applications for the structure in question
# A discussion of any implementation and performance issues

==== Classic problems ====
An article describing a classic problem should generally consist of:
# A statement of the problem.
# A discussion of the relevance of the problem.
# A discussion of the history of the problem if notable.
# A description of solutions to the problem if any exist.
An example is the [[dining philosophers problem]].

==== Design patterns ====
The structure of an article describing a [[software design pattern]] or other [[design pattern]] in computer science (including [[creational pattern]]s, [[structural pattern]]s, [[behavioral pattern]]s, and [[concurrency pattern]]s) should draw on industry best-practice models provided by reliable sources on the subject. Some of these include:
* ''[[Design Patterns|Design Patterns: Elements of Reusable Object-Oriented Software]]'' by Erich Gamma, Richard Helm, Ralph Johnson, and John Vlissides (the "Gang of Four" or GoT; 1994, Addison-Wesley / O'Reilly). Our article on the book at [[Design Patterns#Patterns by type|''Design Patterns'' § Patterns by type]] links to a number of such design-pattern articles. 
* [https://archive.org/details/designpatternsfo00pree ''Design Patterns for Object-Oriented Software Development''] by Wolfgang Pree (1995, Addison-Wesley)
* Various works on design patterns for specific languages and other applications are available for free reading via the Internet Archive Open Library [https://archive.org/search?query=%22design+patterns%22], and a variety of others are hosted on free websites.

==== Fields of study ====
An article describing a field of study within computer science should include:

# A brief overview of the history of the field
# A basic introduction to the key concepts around which the field revolves
# A description of the important principles, theorems, or results produced by the field
# A discussion of relationships with other fields of study (inside and outside CS)
# Some pointers to articles that describe particular aspects of the field in greater detail

==== Formalisms ====
An article describing some kind of formalism should contain:

# A brief outline of the history of the formalism (originator, major developments, etc.)
# An informal introduction to the basic concepts involved (preferably including some simple examples)
# A formal definition
# Discussion of important applications or implementations
# Description of major tools that support the formalism
# Brief overview of related or derived formalisms

A good example is [[lambda calculus]].

==== Programming constructs ====
An article describing a programming construct should generally include:

# A brief overview of what the construct is, and how it is used (perhaps including an informal [[operational semantics]])
# A listing of alternative names for the construct
# Pseudocode or a small code sample demonstrating the construct in use
# Description of any equivalences between the construct and other constructs
# A discussion of any variations in the semantics of the construct
# A discussion of any disadvantages to use of the construct

Examples include [[continuation]], [[closure (computer programming)]], and [[exception handling]].

==== Programming languages ====
An article describing a programming language should generally include at least:

# A brief outline of the history of the language
# An overview of the language features
#* Programming paradigm(s) that the language ''supports'', and ''how well'' it supports them
#* Style of type-checking, support for design by contract or other specification techniques
#* Memory management style
# A basic introduction to the language syntax (including some code samples)
# An overview of the formal semantics of the language (if one exists)
# A list of available implementations and supported platforms

A good example is the [[Rust (programming language)]] article.

==== Theorems and conjectures ====
An article describing theorems or conjectures should generally contain at least:

# A brief informal description of the theorem or conjecture.
# A formal statement of the theorem or conjecture.
# A discussion of the history of the theorem or conjecture.
# A discussion of impacts, consequences, or implications of the theorem or conjecture.

As many computer science theorems and conjectures are often stated informally in popular literature it may also be beneficial to provide some discussion of common misconceptions or misinterpretations of the theorem or conjecture.

The names of such things [[Wikipedia:Manual of Style/Capital letters#Religions, deities, philosophies, doctrines, and their adherents|are not capitalized except where they contain a proper name]] (e.g. a surname).

Good examples include [[halting problem]] and [[Church–Turing thesis]].

==== Tools ====
An article describing a class of tools should generally contain:

# A brief overview of the purpose of the tool
# A brief history of the development of the class of tool
# Discussion of any major subclasses of the tool class
# Brief description of the key underlying algorithms or implementation techniques

Examples include [[compiler]], [[text editor]], and [[automated theorem proving]].

=== Concluding matters===

{{crossref|pw=y|See {{section link|WP:Manual of Style/Layout#Standard appendices and footers}} for use of "See also", "Notes", "References", "External links" sections, and navigation templates.}}

== Style guidelines ==
{{anchor|Style|STYLE|style}}
* [[WP:Manual of Style/Mathematics]] has some good advice on how to discuss more theoretical topics, as well as when and how to include proofs of important theorems. It also includes guidance on how to typeset equations, logical expressions, and other mathematical notation.
* {{section link|WP:Manual of Style/Dates and numbers#Non-base-10 notations}} gives advice on formatting e.g. binary or hexadecimal numbers and memory addresses.

=== Code samples ===
{{shortcut|MOS:CODE|MOS:SOURCE|MOS:SYNTAX}}
{{See also|Help:Wikitext#Text formatting|Help:Wikitext#Pre}}

Samples of actual sources get included in articles for a variety of reasons, although the most typical reasons are to demonstrate the "look" of a particular language, to provide examples of language-specific constructs or features, and to provide examples of algorithms not easily expressed in pseudocode.  While there's nothing inherently wrong with including sample code, excessive amounts of it can detract from the content of the article itself; avoid writing sample code unless it contributes significantly to a fundamental understanding of the encyclopedic content.

{{Wikibooks|Algorithm Implementation|Sorting/Bogosort|Bogosort}}
[[:WP:WWIN#Wikipedia is not a mirror or a repository of links, images, or media files|Wikipedia is not a source code repository]]. Code that is not relevant to encyclopedic content should be moved out of Wikipedia. WikiBooks is the appropriate Wikimedia project for existing GFDL-compatible code; in particular [[Wikibooks:Algorithm Implementation]]. The external [http://literateprograms.org/LiteratePrograms:Welcome LiteratePrograms] and [http://rosettacode.org/ Rosetta Code] wikis are appropriate places to put ''new'' sample implementations, along with descriptions of how those implementations work. '''Important note:''' existing implementations on Wikipedia ''cannot'' be transferred to the LiteratePrograms wiki because Wikipedia content is licensed under the [[GFDL]] and/or [[Wikipedia:CC-BY-SA|CC-BY-SA]], while LiteratePrograms uses the more liberal [[MIT/X11 license]]; relicensing existing code from GFDL/CC-BY-SA to MIT/X11 would require the permission of all copyright holders

Some general guidelines on code samples:

* Sample implementations of algorithms are fine, but every algorithm article should include a [[pseudocode]] description of the core algorithm when possible, so that anyone can understand how the algorithm works. See below for guidelines on pseudocode.
* The sample should use a language that clearly illustrates the algorithm to a reader who is relatively unfamiliar with the language— even if you believe that the language is well-known. To remain language-neutral, choose languages based on clarity, not popularity. Languages that emphasize readability, such as [[Python (programming language)|Python]] and [[Ruby (programming language)|Ruby]], are good choices. Avoid esoteric or language-specific operations.
* Source code implementations must be compatible with the [[GFDL]] and [[Wikipedia:CC-BY-SA|CC-BY-SA]] licenses (which are incompatible with the [[GNU General Public License|GPL]]).
* Multiple source code implementations are not appropriate unless they contrast specific aspects of the code ''and'' that contrast is important to the encyclopedic content of the article.  If possible, accentuate differences by providing the alternate implementation in the same language as the original.
* All code samples should be marked up using one of the following methods:
** Surrounding a {{em|short, inline}} code sample in {{tag|code}} or <code><[[mw:Extension:SyntaxHighlight|syntaxhighlight]] lang="{{var|x}}" inline></code>
** Surrounding a {{em|block}} of code in <code><nowiki><syntaxhighlight lang="x"></nowiki></code> or {{tag|pre}} tags
** Indenting each line of a {{em|block}} of code by one or more spaces (invoking an [[Help:Wikitext#Invisible pre|invisible "pre" tag]]); unlike the above method, this allows you to use basic text formatting like italic, bold, etc. in the sample. This typesets them in a monospaced typeface to ensure that spacing is preserved and provides additional information to [[screen readers]] and users with customized CSS. Doing this is particularly important for languages where whitespace has syntactic significance&mdash; ideally we'd like people to be able to copy and paste sample code into a text editor or IDE.  For example,
<pre>
int main(void) {
    printf("hello, world\n");
    return 0;
}
</pre>
* Syntax highlighting may be obtained by using [[mw:Extension:SyntaxHighlight|SyntaxHighlight]] MediaWiki tag instead of {{tag|pre}}, with a specific <code>lang</code> attribute specifying the language name (the value <code>wikitext</code> is used for MediaWiki markup). See [[mw:Extension:SyntaxHighlight GeSHi#Supported languages|Extension:SyntaxHighlight]] for supported languages. The following is syntax-highlighted Java code, for example, using {{xtag|syntaxhighlight|params=lang{{=}}"java"}}:
<syntaxhighlight lang="java">
class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello World!"); // Print "Hello World!"
    }
}
</syntaxhighlight>
* Since code listings are not line-wrapped, and many people read Wikipedia in space-constrained environments, ensure that code listings have a maximum line length of 60 chars. Apply manual word wrap if necessary.

=== Algorithms ===
{{shortcut|MOS:ALGO|MOS:PSEUDOCODE}}

There are no universally accepted standards for presenting algorithms on Wikipedia. Below, we adot the invisible "pre" method described above. A past attempt at standardized pseudocode is archived at [[User:Dcoetzee/Wikicode]], though "[t]he author advises that such a proposal not be advanced again, as it is unlikely to gain consent". Within [[Wikipedia:WikiProject Computer science|WikiProject Computer science]], the consensus has generally been that where possible, algorithms should be presented in pseudocode. The use of pseudocode is completely language agnostic, and is more NPOV with respect to programming languages in general. Pseudocode also provides far more flexibility with regard to the level of implementation detail, allowing algorithms to be presented at however high a level is required to focus on the algorithm and its core ideas, rather than the details of how it is implemented. Finally, suitably high-level pseudocode provides the most [[Wikipedia:Make technical articles accessible|accessible]] presentation of an algorithm, particularly for non-programmers. 

==== Example ====
 '''algorithm''' ford-fulkerson '''is'''
     '''input:''' Graph ''G'' with flow capacity ''c'', 
            source node ''s'', 
            sink node ''t''
     '''output:''' Flow ''f'' such that ''f'' is maximal from ''s'' to ''t''
 
     ''(Note that f<sub>(u,v)</sub> is the flow from node u to node v, and c<sub>(u,v)</sub> is the flow capacity from node u to node v)''
 
     '''for each''' edge (''u'', ''v'') '''in''' ''G''<sub>''E''</sub> '''do'''
         ''f''<sub>(''u'', ''v'')</sub> &larr; 0
         ''f''<sub>(''v'', ''u'')</sub> &larr; 0
 
     '''while''' there exists a path ''p'' from ''s'' to ''t'' '''in''' the residual network ''G''<sub>''f''</sub> '''do'''
         let ''c''<sub>''f''</sub> be the flow capacity of the residual network ''G''<sub>''f''</sub>
         ''c''<sub>''f''</sub>(''p'') &larr; min{''c''<sub>''f''</sub>(''u'', ''v'') | (''u'', ''v'') '''in''' ''p''}
         '''for each''' edge (''u'', ''v'') '''in''' ''p'' '''do'''
             ''f''<sub>(''u'', ''v'')</sub> &larr;  ''f''<sub>(''u'', ''v'')</sub> + ''c''<sub>''f''</sub>(''p'')
             ''f''<sub>(''v'', ''u'')</sub> &larr; &minus;''f''<sub>(''u'', ''v'')</sub>
 
     '''return''' ''f''

==== General guidelines for writing pseudocode ====
* Make sure the algorithm is understandable without having to read this page first.
* Try to focus on outlining the algorithm, and where possible keep discussion and explanation of the algorithm outside of the pseudocode.
* All assignment, comparison, and other mathematical operators should be rendered with proper mathematical symbols wherever possible:
{| class="wikitable plainrowheaders"
|+ {{sronly|Symbols for use in pseudocode}}
! scope="col" | Operator
! scope="col" | Result
! scope="col" | Entity
! scope="col" | Example
|-
! scope="row" | Assignment
| &larr; or := || &amp;larr;, := || <code>''c'' &larr; 2&pi;''r''</code>, <code> ''c'' := 2&pi;''r''</code>
|-
! scope="row" | Comparison
| =, &ne;, <, >, &le;, &ge; || =, &amp;ne;, <, >, &amp;le;, &amp;ge; ||
|-
! scope="row" | Arithmetic
| +, &minus;, ×, /, mod || +, &amp;minus;, ×, /, mod ||
|-
! scope="row" | Floor/ceiling 
| &lfloor;, &rfloor;, &lceil;, &rceil; || &amp;lfloor;, &amp;rfloor;, &amp;lceil;, &amp;rceil; || <code>''a'' &larr; &lfloor;''b''&rfloor; + &lceil;''c''&rceil;</code>
|-
! scope="row" | Logical
| '''and''', '''or'''
| <nowiki>'''and''', '''or'''</nowiki>
| <code>''a'' &ge; ''b'' '''and''' ''a'' &le; ''c''</code>
|-
! scope="row" | Sums
| &sum; &prod;
| &amp;sum; &amp;prod;
| <code>''h'' &larr; &sum;<sub>''a''&isin;''A''</sub> 1/''a''</code>
|}

===== Low-level pseudocode =====
* All control structure keywords should be bolded, and comments should be in italics (in addition to whatever other manner for denoting comments is used).
* Try to keep the algorithm description sufficiently high level so as to avoid most implementation specific details.
* Try to avoid using structures or techniques that are idiomatic to a particular language or programming paradigm.
* If idiomatic structures or techniques are ''unavoidable'' try to present them in a generic high-level way in line with the style outlined below:
* The preferred conditional structure is
 '''if''' condition '''then'''
     ''code path''
 '''else if''' condition '''then'''
     ''code path''
 '''else'''
     ''code path''
 '''end if'''
* The preferred looping constructs are 
 '''while''' condition '''do'''
     ''code block''
 '''repeat'''
:and
 '''for''' loop_control '''do'''
     ''code block''
 '''repeat'''
:where <code>loop_control</code> is any suitable clause to control a for loop, such as <code>item in list</code> or <code>1 &le; i &le; n</code> etc.
* The preferred function definition structure is
 '''function''' function_name '''is'''
     ''code block''
     '''return''' variable
 '''end function'''
:where <code>function_name</code> is any reasonable format of function name and arguments. Alternatively, inputs and outputs can be specified within the function block:
 '''function''' function_name '''is'''
     '''input:''' ''description of inputs''
     '''output:''' ''description of outputs''
     ''code block''
     '''return''' variable
 '''end function'''
* Code blocks should be indented. If sufficiently clear, block closing keywords ('''end''', '''repeat''' etc.) may be omitted.
An example of pseudocode roughly hewing to these guidelines is provided as the example on the [[Algorithm#Example|Algorithm]] page, and in [[Bucket sort]],  [[Topological sort]], and [[Pollard's rho algorithm]].

===== High-level pseudocode =====

* Algorithms that are most easily presented at a very high level, such as [[Buchberger's algorithm]] or the [[Pohlig–Hellman algorithm]] should be presented in the format
:'''Inputs''' ''description of input arguments''
:'''Output''' ''description of outputs''
:# ''(description of a step in the algorithm)''
:# ''(the next step in the algorithm)''
:## ''(substep)''
:# ''(etc.)''
:using markup:
{{sxhl|2=wikitext|
:'''Inputs''' ''description of input arguments''
:'''Output''' ''description of outputs''
:# ''(description of a step in the algorithm)''
:# ''(the next step in the algorithm)''
:## ''(substep)''
:# ''(etc.)'' 
}}
* Descriptions of steps should be high level, and may simply be English sentences.
* Substeps of the algorithm, due to branch conditions or loop structures should be indented and subnumbered.
* Termination of the algorithm with a return value should be denoted using the keyword '''return'''

Examples of algorithms in this format include [[Buchberger's algorithm]], [[Pohlig–Hellman algorithm]], [[Itoh–Tsujii inversion algorithm]], [[Baby-step giant-step]], and [[Pollard's p − 1 algorithm|Pollard's ''p''&nbsp;&minus;&nbsp;1 algorithm]].

== Including references ==
{{anchor|Including literature and references|reason=Old section name using "literature" which is not a term WP usually employs in this context Redundant anyway.}}
It is [[Wikipedia:Verifiability|essential for article content to be verifiable with reliable sources]], a well-chosen list of references and pointers to the literature. Any quotation, any material challenged or likely to be challenged, and any claim that involves a living person [[Wikipedia:Verifiability#Responsibility for providing citations|{{em|must}}]] be supported by an [[Wikipedia:Citing sources#Inline citations|inline citation]] to a reliable secondary source. Some additional reasons for citing high-quality sources are the following:

* Providing proper source citations enables other editors and our readers to verify the given information and evaluate the sources. This is especially important in any science topic, since the state of the art is always advancing.
* A reader may desire more details, but Wikipedia is not a [[Wikipedia:What Wikipedia is not#Wikipedia is not a manual, guidebook, textbook, or scientific journal|substitute for a textbook]] (that is what [[Wikibooks]] is for). Many research papers and books of benefit to topical newcomers are now freely available online.
* Some notions are defined differently depending on context or author. Articles require references that support the given usage, and should identify conflicting usages (giving [[Wikipedia:Neutral point of view#Due and undue weight|due weight]] to the sources for them).
* Important algorithms, theorems, or definitions should cite the concept-originating papers as historical and technical information, in addition to later secondary reference works relied on for modern, applied context.

[[Wikipedia:No original research#Primary, secondary and tertiary sources|Primary sources]] must be used with care. They are [[Wikipedia:Verifiability#Self-published or questionable sources as sources on themselves|generally permissible]] for non-controversial and non-promotional claims about the subject or its author(s). Examples: referencing a blog post from the [[Rust (programming language)|Rust programming language]] development team is sufficient for a point about the internal architecture of the Rust compiler, or the motivation behind a specific decision about the Rust language design. However, such a source cannot be used for providing Rust benchmarks, or contrasting Rust's features versus those of another language, since such claims from the developers may have a promotional element and involve analysis, evaluation, interpretation, or synthesis of facts and evidence, which [[WP:AEIS|requires a secondary source]].

[[Wikipedia:Citing sources#Citation style|Wikipedia does not enforce a specific reference and citation style]]; just use one consistently within a particular article.

{{crossref|pw=y|See [[WP:Citing sources]] for how to cite sources properly.}}

==See also==
* [[Wikipedia:WikiProject Computer science]]
* [[WP:MOSBPS]] - style guide for data rates

==Further reading==
* {{cite book |first=Justin |last=Zobel |date=2004 |title=Writing for Computer Science |edition=2nd |publisher=Springer |isbn=1-85233-802-4 |ref=none}}

[[Category:Wikipedia Manual of Style (science)]]
[[Category:WikiProject Computer science]]