Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
review till line 800
  • Loading branch information
JuanitoFatas committed Jan 25, 2013
1 parent 46f632d commit 7b549f7
Showing 1 changed file with 15 additions and 45 deletions.
60 changes: 15 additions & 45 deletions GoogleCLSG-zhCN.xml
Expand Up @@ -684,18 +684,15 @@ Robert Brown
并通过编程工具,如 IDE 来显示。或是通过在 REPL 下查询,如 <code>(describe 'foo)</code>;放在网上的文档或其他参考着作也可以在文档字串的基础上来创建。因此,文档字串是给你的 API 撰写文档的完美地点。应该描述如何使用代码(包括需要避开的陷阱),而不是代码是如何工作的(以及之后所需的工作),这两个是你该放在注解的东西。
</p>
<p>
当定义一个顶层及别的函数、类型、类别、变量以及宏时,提供一个文档字串。
一般则是在程序语言允许加入文档的地方,添加文档字串。
当定义一个顶层及别的函数、类型、类别、变量以及宏时,提供一个文档字串。一般则是在程序语言允许加入文档的地方,添加文档字串。
</p>
<p>
关于函数,docstring 应该要描述函数的合约:
这个函数干什么,
这个函数的参数表示什么,
这个函数所返回的值,
这个函数可捕捉的状况。
应该在适当的抽象层级上来表达,解释意图,而不仅是解释语法。
在文档字串里,将 Lisp 符号的名字转为大写,比如函数参数。
打个比方,"The value of LENGTH should be an integer."
应该在适当的抽象层级上来表达,解释意图,而不仅是解释语法。在文档字串里,将 Lisp 符号的名字转为大写,比如函数参数。打个比方,"The value of LENGTH should be an integer."
</p>
<CODE_SNIPPET>
(defun small-prime-number-p (n)
Expand All @@ -717,14 +714,10 @@ Robert Brown
associations, and returns the table itself."))
</CODE_SNIPPET>
<p>
一个长的 docstring 通常用一句话的总结开始是有用的,
接着才是 docstring 的主要内容。
一个长的 docstring 通常用一句话的总结开始是有用的,接着才是 docstring 的主要内容。
</p>
<p>
当一个类型的名称被使用时,
符号可以用反引号及单引号包围,
反引号在前,单引号在后。
Emacs 会将类型高亮,而高亮作为读取器的线索,
当一个类型的名称被使用时,符号可以用反引号及单引号包围,反引号在前,单引号在后。Emacs 会将类型高亮,而高亮会变成读取器的线索,
<kbd>M-.</kbd> 会跳转到符号的定义。
</p>
<CODE_SNIPPET>
Expand All @@ -734,16 +727,11 @@ Robert Brown
...)
</CODE_SNIPPET>
<p>
当特化影响了方法的行为,
超出通用函数的 docstring 所描述的内容时,
应该给通用函数的每一个方法各自撰写文档。
当特化影响了方法的行为,超出通用函数的 docstring 所描述的内容时,应该给通用函数的每一个方法各自撰写文档。
</p>
<p>
当你修补了一个错误,
思考看看修补后的代码是否正确,还是是错误的;
如果不对的话,你必须添加一个注解,
从修补错误的观点来解释代码。
如果可以的话,添加错误序号,也是推荐的。
当你修补了一个错误,思考看看修补后的代码是否正确,还是是错误的;如果不对的话,你必须添加一个注解,
从修补错误的观点来解释代码。如果可以的话,添加错误序号,也是推荐的。
</p>
</BODY>
</STYLEPOINT>
Expand All @@ -753,44 +741,26 @@ Robert Brown
</SUMMARY>
<BODY>
<p>
注解是给未来维护代码的人的说明。
即便你是唯一能够看与触摸代码的人,
即便你长生不老或是永远不离职,
或是离职之后根本不管的人(并在这种万一的情况下使你的代码自行毁灭),
你可能会发现给代码写注解是有帮助的。
当然啦,在几个礼拜、月、年之后,回头看看代码时,
你会发现当初写这个代码的人,完全与你不是同一个人,
则你会感激当初自己有留下注解。
注解是给未来维护代码的人的说明。即便你是唯一能够看与接触到代码的人,即便你长生不老或是永远不离职,或是离职之后根本不管的人(并在这种万一的情况下使你的代码自行毁灭),你可能会发现给代码写注解是有帮助的。当然啦,在几个礼拜、月、年之后,回头看看代码时,你会发现当初写这个代码的人,完全与你不是同一个人,则你会感激当初自己有留下注解。
</p>
<p>
你必须给任何复杂的代码留注解,
这样一来下个开发者才可以了解情况。
(又来了,“hit by a truck” 理论。)
你必须给任何复杂的代码留注解,这样一来下个开发者才可以了解情况。(又来了,“hit by a truck” 理论。)
</p>
<p>
注解也可以作为指引阅读代码的人的一种方式,
这样他们才知道这里有什么。
注解也可以作为指引阅读代码的人的一种方式,这样他们才知道这里有什么。
</p>
<ul>
<li>
文件表头及源文件里大段代码的重要注解,
注解应该使用四个分号。
文件表头及源文件里大段代码的重要注解,注解应该使用四个分号。
</li>
<li>
一个顶层级别的形式或是小组的顶层级别形式,
注解应该使用三个分号。
一个顶层级别的形式或是小组的顶层级别形式,注解应该使用三个分号。
</li>
<li>
在一个顶层级别的形式里,
如果注解出现在行之间,
注解应该使用两个分号。
在一个顶层级别的形式里,如果注解出现在行之间,注解应该使用两个分号。
</li>
<li>
如果是一个括号的备注且出现在行的最后,
注解应该使用一个分号。
你应该使用空格来分离注解与引用的代码,
使得注解脱颖而出。
你应该试着垂直排列相关的行尾注解。
如果是一个括号的备注且出现在行的最后,注解应该使用一个分号。你应该使用空格来分离注解与引用的代码,使得注解脱颖而出。你应该试着垂直排列相关的行尾注解。
</li>
</ul>
<CODE_SNIPPET>
Expand Down Expand Up @@ -832,7 +802,7 @@ Robert Brown
</STYLEPOINT>
<STYLEPOINT title="标点与文法">
<SUMMARY>
你应该使用正确的标点符号来写文档
应该使用正确的标点符号来写文档
</SUMMARY>
<BODY>
<p>
Expand Down

0 comments on commit 7b549f7

Please sign in to comment.