GNU 编码标准 Part 1

GNU编码标准@author{Richard Stallman} @author{last updated 03 Feb 1993}
Copyright (C) 1992, 1993 Free Software Foundation
Permission is granted to make and distribute verbatim copies of this manual
provided the copyright notice and this permission notice are preserved on al
l copies.
Permission is granted to copy and distribute modified versions of this manua
l under the conditions for verbatim copying, provided that the entire result
ing derived work is distributed under the terms of a permission notice ident
ical to this one.
Permission is granted to copy and distribute translations of this manual int
o another language, under the above conditions for modified versions, except
that this permission notice may be stated in a translation approved by Free
Software Foundation.
----------------------------------------------------------------------------
----
本文由王立翻译. 1999.11.9
引用私有程序
不要在任何情况下,为你在的GNU中的工作或者在工作中引用Unix的源代码（或者任何其
它私有程序）。
如果你对一个Unix程序内容有一些模糊的记忆，这并不因为着你绝对写程序来模仿它，
但请试图在内部使用不同的代码行来组织它，因为这将使你工作的结果在细节上与Unix
版本有所不同。
例如，Unix工具通常进行了优化以使用最少的内存；如果你更希望提高速度，你的程序
将会有很大的不同。你可以在内核中保存整个输入文件并且在内存中扫描而不是使用st
dio。使用比Unix程序更新的、更明智的算法。不使用暂时文件。在一遍扫描而不是两遍
扫描中完成任务（我在assembler（汇编器）中这样做了）。
或者相反，强调简单性而不是速度。对于一些应用程序来说，今天的计算机只要使用简
单的算法就够了。
或者注重一般性。例如，Unix程序通常使用静态的表格和固定大小的字符串，这导致了
不可改变的限制；用动态分配来代替。确认你的程序处理了输入文件为空和其它滑稽的
情况。为增加扩展性而增加一种程序语言并且用那种语言完成程序的一个部分。
或者把程序的一部分修改成独立的库。或者用一个简单的废物收集器而不是在释放内存
的时候精确地进行跟踪，或者使用诸如obstacks这样的新的GNU工具。
接受他人的奉献
如果其他人发给你一段添加到你正在编写程序中的代码，我们需要准许使用它的法律文
书 --我们将需要从你那里取得同样的法律文书。程序的每个重要的贡献者都必须签署某
种法律文书以使得我们可以给程序一个清晰的标题。仅有主要作者是不够的。
所以，在把来自于他人的任何共享添加到程序中之前，告诉我们以便我们可以做出安排
以获取文书。在你实际地使用贡献之前，请等待直到我们告诉你我们已经收到了签署的
文书。
这即适用于你发行程序之前也适用于发行之后。如果你收到了一个修正bug的补丁，并且
它们做了主要的修改，我们就需要为他提供法律文书。
你不需要为这里或者那里的少数几行修改提供文书，因为对于达到版权目的没有意义。
还有，如果你从建议中获得的仅仅是一些想法，而不是你实际上使用的代码，你也不需
要文书。例如，如果你写了一个程序的不同解决方案，你并不需要获得许可文书。
我知道这是十分麻烦的；它对我们来说也十分麻烦。但如果你不等待，你就可能误入歧
途，如果这个贡献者的雇主不肯签署弃权声明怎么办？你可能不得不再次把代码剔除出
来！
最糟糕的情况是如果你忘记告诉我们其它的贡献者，我们可能会因此而窘迫地出现在法
庭上。
修改日志（Change Logs）
为每个目录维护一个修改日志，以记述对这个目录下源文件的修改。这样做的目的是使
得在将来寻找bug的人可以指导大致是那些修改导致了错误。通常，一个新的bug可以在
最近进行的修改中被找到。更重要的事，修改日志有助于消除程序的不同部分之间在概
念上的不一致性；它们可以告诉我们概念冲突产生的历史。
使用Emacs命令M-x add-change在修改日之中创建一个新的条目。一个条目应该包含一个
星号、被修改的文件的名称以及被扩在括号内的、被修改了的函数、变量或者任何东西
。括号之后是冒号和对你对函数或变量的修改的说明。
用空行把无关的条目分隔开。如果两个条目反映了同一个修改，因而它们一同工作，那
就不要在它们之间使用空行。如果后续的条目针对的是相同的文件，那么你可以忽略文
件名的星号。
下面是一些例子：
* register.el (insert-register): Return nil.
(jump-to-register): Likewise.
* sort.el (sort-subr): Return nil.
* tex-mode.el (tex-bibtex-file, tex-file, tex-region):
Restart the tex shell if process is gone or stopped.
(tex-shell-running): New function.
* expr.c (store_one_arg): Round size up for move_block_to_reg.
(expand_call): Round up when emitting USE insns.
* stmt.c (assign_parms): Round size up for move_block_from_reg.
在这里没有必要叙述修改的完整目录和它们是如何协同工作的。把这些说明作为注释放
到代码中更好一些。这就是说为什么只要给出“New function”就够了；在源代码中，
与函数放在一起的注释说明了它是做什么的。
然而，有时为一大堆修改写上一行文字以描述它们的整体目的是有用的。
在概念上，你可以把修改日志看作解释原始版本与当前版本的不同的“undo列表”。人
们可以阅读当前的版本；他们不需要修改日志告诉他们其中有什么。他们从修改日之中
得到的是关于早期版本的不同的清晰解释。
在你以简单的方式修改函数的调用顺序，并且你修改了所有对函数的调用时，不必为所
有的调用创建单独的条目。只要在被调用的函数的条目中写“All callers changed.”
即可。
在你仅仅修改了注释或者文档字符串的时候，为该文件写一个条目，而不必提到函数，
就足够了。只要写"Doc fix."。不必为文档文件维护修改日志。这是因为文档不那么容
易受到难以修正的错误的影响。文档不是由那些必须以精确地工程方式相互作用的部分
组成的；要修改一个错误，你不需要知道这个错误传播的历史。
与其它实现的兼容性
作为一个特例，对于GNU中的工具程序和库，它们应该和Berkeley Unix相应的部分向上
兼容，如果标准C定义了它们的行为，那它们应该和标准C向上兼容，如果POSIX规范定义
了它们的行为，那它们也应该与POSIX规范向上兼容。
当这些标准发生冲突的时候，为每个标准提供兼容模式是有用的。
标准C和POSIX禁止进行任何形式的扩展。自由地进行你的扩展，并且把选项 `--ansi'或
`--compatible'包括进来以关闭你的扩展。但是如果扩展很可能导致任何实际程序或者
脚本的崩溃，那么它可能实际上不是向上兼容的。尝试一下重新定义它的界面。
当一个特征仅仅被用户（而不会被程序或者命令文件）所使用的时候，并且在Unix中它
完成得并不好，请自由地用完全不同并且更好的方式代替它。（例如，用Emacs代替vi。
）但同时提供兼容模式仍然是很好的。（现在有自由的vi实现，所以我们提供了它。）

欢迎提供Berkeley Unix没有提供的有用功能。Unix中没有的附加功能可能是有用的，但
我们优先复制那些Unix已经有的功能。
php爱好者站 http://www.phpfans.net PHP|MySQL|javascript|ajax|html.