8 文檔

8.1 標注代碼的屬性

必須在模塊頭部正確標注代碼的屬性。聲明模塊的所有思路來源。如果代碼來源于其他代碼，要注明來源及作者。

Never steal code - stealing code is taking code from some other module editing it and forgetting to say who wrote the original.

永遠不要偷竊代碼（從別的模塊剽竊得來而又不注明原作者）。

以下是一些有用的屬性范例：

-revision('Revision: 1.14 ').
-created('Date: 1995/01/01 11:21:11 ').
-created_by('eklas@erlang').
-modified('Date: 1995/01/05 13:04:07 ').
-modified_by('mbj@erlang').  

8.2 要在代碼中提供關(guān)于規(guī)范的引用

在代碼中提供一些指向用于理解代碼的文檔的交叉引用。比如，如果代碼實現(xiàn)了一些通信協(xié)議或硬件接口，則要提供用于編寫代碼的文檔所在的頁碼，或者是一份確切的引用。

8.3 記錄所有錯誤

必須將所有的錯誤保存在一份獨立的文檔中，并記錄下錯誤的含義和原因（參見 10.4 節(jié)內(nèi)容）。

這里所說的錯誤是系統(tǒng)已經(jīng)檢測出來的錯誤。

有時，可能會在程序中用錯誤日志記錄函數(shù)來偵測邏輯錯誤：

error_logger:error_msg(Format, {Descriptor, Arg1, Arg2, ....})

這時要確保將 {Descriptor, Arg1,...} 添加到錯誤消息文檔中。

8.4 將消息中的首要數(shù)據(jù)結(jié)構(gòu)記錄下來

在系統(tǒng)不同部分間傳遞消息時，使用標記元組作為首要數(shù)據(jù)結(jié)構(gòu)。

Erlang 的記錄特性（自 Erlang 4.3 版起引入）可用于確保模塊數(shù)據(jù)結(jié)構(gòu)的一致性。

應(yīng)該記錄下數(shù)據(jù)結(jié)構(gòu)的文本描述（參見 10.2 節(jié)內(nèi)容）。

8.5 注釋

注釋應(yīng)該清晰準確，避免不必要的廢話，而且要保證注釋與代碼保持一致更新。注釋可以增進對代碼的理解。注釋應(yīng)該用文本來編寫。

關(guān)于模塊的注釋不應(yīng)有縮進，開始前應(yīng)帶有三個百分號字符（%%%），參見 8.10 節(jié)內(nèi)容。

關(guān)于函數(shù)的注釋不應(yīng)帶有縮進，開始前應(yīng)帶有 2 個百分號字符（%%），參見 8.6 節(jié)內(nèi)容。

Erlang 代碼中的注釋應(yīng)帶有一個百分號字符（%）。如果一個代碼行只包含一個注釋，它會被認定為 Erlang 代碼而進行縮進。這種注釋應(yīng)放置在它所針對的語句前。如果注釋可以和語句放在同一行中，則優(yōu)先考慮這種方式。

%% 關(guān)于函數(shù)的注釋  
some_useful_functions(UsefulArgugument) ->
  another_functions(UsefulArgugument),    % 代碼行尾的注釋
  % 關(guān)于 complicated_stmnt 的注釋，縮進級別等同  
  complicated_stmnt,
......

8.6 注釋每一個函數(shù)

文檔應(yīng)重點記錄的信息如下所示：

• 函數(shù)的用意；
• 函數(shù)有效輸入范圍。具體來說，即是函數(shù)參數(shù)的數(shù)據(jù)結(jié)構(gòu)及其含義。
• 函數(shù)輸出范圍。具體是指返回值所有可能的數(shù)據(jù)結(jié)構(gòu)及其具體含義。
• 如果函數(shù)實現(xiàn)了一個復(fù)雜的算法，則要對它進行描述。
• 可能由exit/1, throw/1 或任何不明顯的運行時錯誤所產(chǎn)生的失敗和退出信號的可能原因。
• 函數(shù)可能導(dǎo)出的任何副作用。

范例：

%%----------------------------------------------------------------------
%% Function: get_server_statistics/2
%% Purpose: Get various information from a process.
%% Args:   Option is normal|all.
%% Returns: A list of {Key, Value} 
%%     or {error, Reason} (if the process is dead)
%%----------------------------------------------------------------------
get_server_statistics(Option, Pid) when pid(Pid) ->
  ......  

8.7 數(shù)據(jù)結(jié)構(gòu)

定義記錄時，應(yīng)該加入簡明的文字描述。范例如下：

%% File: my_data_structures.h

%%---------------------------------------------------------------------
%% Data Type: person
%% where:
%%    name: A string (default is undefined).
%%    age: An integer (default is undefined).
%%    phone: A list of integers (default is []).
%%    dict:     A dictionary containing various information about the person. 
%%       A {Key, Value} list (default is the empty list).
%%----------------------------------------------------------------------
-record(person, {name, age, phone = [], dict = []}).  

8.8 文件頭部，版權(quán)聲明

每個源代碼文件必須都要寫明版權(quán)信息。示例如下：

%%%--------------------------------------------------------------------- 
%%% Copyright Ericsson Telecom AB 1996
%%%
%%% All rights reserved. No part of this computer programs(s) may be 
%%% used, reproduced,stored in any retrieval system, or transmitted,
%%% in any form or by any means, electronic, mechanical, photocopying,
%%% recording, or otherwise without prior written permission of 
%%% Ericsson Telecom AB.
%%%---------------------------------------------------------------------   

8.9 File headers, revision history 文件頭部，修訂歷史

每個源代碼文件都應(yīng)記錄下代碼的修訂歷史，其中要清晰地標注上修改文件的人及其修改內(nèi)容。

%%%--------------------------------------------------------------------- 
%%% Revision History
%%%--------------------------------------------------------------------- 
%%% Rev PA1 Date 960230 Author Fred Bloggs (ETXXXXX)
%%% Intitial pre release. Functions for adding and deleting foobars
%%% are incomplete
%%%--------------------------------------------------------------------- 
%%% Rev A Date 960230 Author Johanna Johansson (ETXYYY)
%%% Added functions for adding and deleting foobars and changed 
%%% data structures of foobars to allow for the needs of the Baz
%%% signalling system
%%%---------------------------------------------------------------------   

8.10 文件頭部，描述信息

每個源代碼文件頭部必須帶有一個關(guān)于該文件所包含模塊的簡單描述信息，以及所有導(dǎo)出函數(shù)的簡要概述。

%%%--------------------------------------------------------------------- 
%%% Description module foobar_data_manipulation
%%%--------------------------------------------------------------------- 
%%% Foobars are the basic elements in the Baz signalling system. The
%%% functions below are for manipulating that data of foobars and for
%%% etc etc etc
%%%--------------------------------------------------------------------- 
%%% Exports
%%%--------------------------------------------------------------------- 
%%% create_foobar(Parent, Type)
%%%   returns a new foobar object
%%%   etc etc etc
%%%---------------------------------------------------------------------   

如果存在任何缺陷、Bug，或者重點測試的特性，則要將它們記錄在一個特殊的注釋里，不要隱藏這些信息。如果模塊中的某些部分還未完成，則要添加一個特殊的注釋。另外，為了便于將來對模塊進行維護，可以把任何相關(guān)信息加以注釋記錄。假設(shè)已完成的產(chǎn)品中包含你所編寫的模塊，你應(yīng)保證在十年內(nèi)，其他人（有可能你根本不認識）仍能變更或改善它們。

8.11 對于陳舊代碼，不要注釋掉，直接移除它們

關(guān)于陳舊代碼的用意，可以在修訂歷史中加入一條注釋。別忘了，源代碼控制系統(tǒng)能幫你。

8.12 使用源代碼控制系統(tǒng)

所有非項目都必須使用源代碼控制系統(tǒng)（如 RCS、CVS 或 Clearcase），他們能保存所有模塊的更改信息。