維基專題:電腦和信息技術/格式手冊
 |
本手冊包含一些建議，旨在幫助您撰寫清晰、美觀且有趣的計算機科學文章。本指南是對一般風格手冊的補充。
計算機科學文章的建議結構
[編輯]撰寫任何技術文章最困難的部分可能是難以滿足讀者的技術知識水平。一般方法是從簡單開始，然後隨着文章的進展轉向更正式和技術性的陳述。以下結構僅是建議；編輯自由裁量權和共識可能會找到更適合某些主題的替代結構。
文章簡介
[編輯]文章應以長度與文章內容相適應的導言部分開頭，該部分以一般術語描述主題並適當總結文章。此開篇材料應使普通讀者快速了解該概念。指出該概念所屬的計算機科學領域並描述該術語的使用背景。用粗體寫出文章標題和任何替代名稱。包括歷史動機、提供一些名稱和日期等。以下是一個例子：
在計算機科學中，通信順序進程（英語：Communicating sequential processes，縮寫為CSP），又譯為交談循序程式、交換訊息的循序程式，是一種形式語言，用來描述並行性系統間進行互動的模式。它是叫做進程代數或進程演算的關於並發的數學理論家族的一員，基於了通過通道的消息傳遞。CSP高度影響了Occam的設計，也影響了程式語言如Limbo、RaftLib、Go、 Crystal和Clojure的core.async等。
CSP最早出現於東尼·霍爾在1978年發表的論文，但在之後又經過一系列的改善。CSP已經實際的應用在工業之中，作為一種工具去規定和驗證各種不同系統的並發狀況，比如T9000 Transputer。CSP的理論自身仍是活躍研究的主題，包括了增加它的實際可應用性的範圍（比如增大可以跟蹤分析的系統的規模）。
背景與應用
[編輯]文章主體部分最好以非正式的介紹開始，通常以「背景」為標題，但也使用「概述」，讓非技術讀者對所介紹主題的基本概念有一個基本的了解。如果所討論的概念有些理論性，那麼在文章頂部簡明扼要地描述其目的或應用用途會很有幫助，可以在導語部分或導語後的介紹部分中描述。提供一些有代表性的例子也很有用，這些例子既可以擴展所討論的概念，也可以提供一些背景信息，說明人們為什麼想要使用該概念。
圖片是闡明觀點的好方法，而且通常甚至可以先於概念的技術討論。 如果介紹材料中沒有包含關於概念歷史的部分，那麼這部分通常很有用，可以提供額外的見解。這通常會形成文章的「歷史」部分。
構建不同類型的文章
[編輯]計算機科學是一個涵蓋多種不同思想的廣闊領域。文章主體部分的結構會因文章類型的不同而有所差異。以下是構建幾種不同類型計算機科學文章的通用準則。這些準則儘可能包含一兩篇「優秀」文章的示例，即能夠展現我們在該特定類別文章中所追求的風格的文章。請始終牢記，這些只是「準則」，而非硬性規定：有些文章需要偏離此結構；有些文章難以歸類；有些文章則完全不符合這些分類。在應用這些準則時，請運用常識。
算法和數據結構
[編輯]一篇關於算法的文章通常應包含以下內容：
- 算法描述（包括偽代碼）
- 對算法時間和空間複雜度的正式討論
- 對任何實現和性能問題的討論
一篇關於數據結構的文章應該包含以下內容：
- 結構描述，以及可在該結構上執行的任何操作
- 所討論結構的應用概述
- 任何實現和性能問題的討論
經典問題
[編輯]一篇描述經典問題的文章通常應該包含以下內容：
- 問題描述。
- 問題相關性討論。
- 問題歷史的討論（如有）。
- 問題解決方案的描述（如有）。
例如：哲學家就餐問題。
設計模式
[編輯]一篇描述軟件設計模式或其他計算機科學中的設計模式（包括創建型模式，結構型模式，行為型模式，以及併發型模式）的文章結構應借鑑可靠來源提供的行業最佳實踐模型。這些可靠來源包括：
- 《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).
- 面向對象軟件開發的設計模式 by Wolfgang Pree (1995, Addison-Wesley)
- 各種關於特定語言和其他應用程式的設計模式的著作可通過互聯網檔案開放圖書館[1]免費閱讀，其他各種著作也託管在免費網站上。
研究領域
[編輯]描述計算機科學領域研究的文章應包含以下內容：
- 該領域歷史的簡要概述
- 該領域核心概念的基本介紹
- 該領域的重要原理、定理或成果的描述
- 與其他研究領域（計算機科學內部和外部）關係的討論
- 一些更詳細地描述該領域特定方面的文章的連結
形式主義
[編輯]描述某種形式主義的文章應包含以下內容：
- 形式主義歷史的簡要概述（創始人、主要發展等）
- 所涉及基本概念的非正式介紹（最好包含一些簡單的例子）
- 形式化定義
- 重要應用或實現的討論
- 支持該形式主義的主要工具的描述
- 相關或派生形式主義的簡要概述
λ演算就是一個很好的例子。
編程結構
[編輯]描述編程結構的文章通常應包含以下內容：
- 簡要概述該結構的含義及其使用方法（可能包括非正式的操作語義）
- 該結構的替代名稱列表
- 演示該結構用法的偽代碼或簡短代碼示例
- 該結構與其他結構之間任何等價性的描述
- 該結構語義上任何變體的討論
- 該結構使用過程中任何缺點的討論
示例包括續體、閉包 (計算機科學)和異常處理。
程式語言
[編輯]一篇描述程式語言的文章通常至少應包含以下內容：
- 語言歷史簡介
- 語言特性概述
- 該語言「支持」的編程範式及其支持程度
- 類型檢查風格、對契約式設計或其他規範技術的支持
- 內存管理風格
- 語言語法的基本介紹（包括一些代碼示例）
- 語言形式語義概述（如有）
- 可用實現和支持平台列表
Rust (程式語言) 文章就是一個很好的例子。
定理和猜想
[編輯]一篇描述定理或猜想的文章通常至少應包含以下內容：
- 對定理或猜想的簡要非正式描述。
- 對定理或猜想的正式陳述。
- 討論該定理或猜想的歷史。
- 討論該定理或猜想的影響、後果或含義。
由於許多計算機科學定理和猜想在通俗文學中經常以非正式的方式表述，因此，對一些常見的關於該定理或猜想的誤解或誤解進行討論也可能會有所幫助。
工具
[編輯]描述一類工具的文章通常應包含以下內容：
- 簡要概述該工具的用途
- 簡要介紹該工具的發展歷史
- 討論該工具類的主要子類
- 簡要描述關鍵底層算法或實現技術
格式指引
[編輯]
- Wikipedia:格式手冊/數學提供了一些關於如何討論更理論性話題的實用建議，以及何時以及如何包含重要定理的證明。它還包括關於如何排版方程式、邏輯表達式和其他數學符號的指導。
代碼示例
[編輯]文章中包含實際原始碼示例的原因有很多，最常見的原因包括展示特定語言的「外觀」、提供該語言特有的結構或特性示例，以及提供難以用偽代碼表達的算法示例。雖然包含示例代碼本身並無不妥，但過多的示例代碼會分散讀者對文章內容的注意力；除非示例代碼對理解百科全書內容有顯著幫助，否則應避免編寫示例代碼。
維基百科並非原始碼庫。與百科全書內容無關的代碼應從維基百科移出。對於現有的符合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
編寫偽代碼的一般準則
[編輯]- 確保算法無需閱讀本頁即可理解。
- 儘量專注於概述算法，並儘可能將算法的討論和解釋放在偽代碼之外。
- 所有賦值、比較和其他數學運算符應儘可能使用正確的數學符號表示：
| Operator | Result | Entity | Example |
|---|---|---|---|
| Assignment | ← or := | ←, := | c ← 2πr, c := 2πr
|
| Comparison | =, ≠, <, >, ≤, ≥ | =, ≠, <, >, ≤, ≥ | |
| Arithmetic | +, −, ×, /, mod | +, −, ×, /, mod | |
| Floor/ceiling | ⌊, ⌋, ⌈, ⌉ | ⌊, ⌋, ⌈, ⌉ | a ← ⌊b⌋ + ⌈c⌉
|
| Logical | and, or | '''and''', '''or''' | a ≥ b and a ≤ c
|
| Sums | ∑ ∏ | ∑ ∏ | 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 輸出描述
- (對算法其中一步的描述)
- (算法中的下一步驟)
- (子步驟)
- (etc.)
- 使用標記語言:
:'''Inputs''' ''输入参数描述''
:'''Output''' ''输出描述''
:# ''(对算法其中一步的描述)''
:# ''(算法中的下一步骤)''
:## ''(子步骤)''
:# ''(etc.)''
- 步驟描述應簡潔明了，可以用簡單的句子概括。
- 由於分支條件或循環結構而產生的算法子步驟應縮進並編號。
- 算法終止並返回值時，應使用關鍵字return來表示。
這種格式的算法示例包括大步小步算法、布赫伯格算法、波利格-赫爾曼算法、en:Itoh–Tsujii inversion algorithm以及en:Pollard's p − 1 algorithm。
包含參考資料
[編輯]文章內容必須能夠通過可靠的來源進行驗證，並附上精心挑選的參考文獻列表和文獻連結。任何引用、任何受到質疑或可能受到質疑的內容，以及任何涉及在世人物的論斷，都必須以可靠的二手資料作為內文引用。引用高質量來源的其他原因如下：
- 提供正確的來源引用能夠幫助其他編輯和讀者驗證所提供的信息並評估來源。這在任何科學領域都尤為重要，因為科學領域的研究總是在不斷發展。
- 讀者可能需要更多細節，但維基百科不能替代教科書（Wikibooks才是教科書的用途）。許多對該領域新手有益的研究論文和書籍現在都可以在網上免費獲取。
- 某些概念的定義會因上下文或作者的不同而有所差異。文章需要提供支持特定用法的參考文獻，並應指出相互衝突的用法（並充分考慮其來源）。
- 重要的算法、定理或定義除了引用後來用於現代應用背景的二手參考文獻外，還應引用概念起源論文作為歷史和技術信息。
必須謹慎使用一手資料。一般來說，一手資料適用於對主題或其作者的非爭議性、非推廣性陳述。例如：引用Rust程式語言開發團隊的博客文章足以說明Rust編譯器的內部架構，或Rust語言設計中某個特定決策背後的動機。但是，此類資料不能用於提供Rust基準測試數據，或對比Rust與其他語言的特性，因為開發者的此類陳述可能帶有推廣性質，並且涉及對事實和證據的分析、評估、解釋或綜合，而這些都需要使用二手資料。
維基百科不強制要求特定的參考文獻和引用格式；只需在同一篇文章中保持一致即可。
See also
[編輯]Further reading
[編輯]- Zobel, Justin. Writing for Computer Science 2nd. Springer. 2004. ISBN 1-85233-802-4.