哲思黑客手册

作者：徐继哲

哲思文档开发者手册
哲思源代码编写规范

哲思文档开发者手册

自由软件需要自由文档，在这里，我们将创作、翻译一些高质量的中文文档。我们的文档都采用XHTML/CSS的形式发布，这和WWW初衷吻合。因此，所有的文档都保存在www.zeuux.org主机上面，www.zeuux.org的内容通过CVS管理。所有的文件以UTF-8编码方式保存。

能力要求

有强烈的贡献社会和分享经验的欲望。
熟悉自己要撰写文档的领域。
良好的写作基础。
熟悉XHTML/CSS。
熟练使用CVS。

目录介绍

/www/js：JavaScript源代码，包括ZEUUX.org的标准头、标准尾、二级目录等。
/www/style：ZEUUX.org样式表和文档模板。
其他的都是按照文档的性质分类的目录。

文件命名规范

文档的名字要符合内容，用文档的标题来作为文档的名字，中间用"-"连接，比如：www-committer-handbook.cn.html，力求URL有很好的可读性。ZEUUX.org是多语言网站，.html代表英文版；.cn.html代表中文版；.jp.html代表日文版，等等。

翻译中英文术语对照表

中文	英文	说明
自由软件	free software	自由软件强调的是用户使用软件的自由，而不是价格。
专有软件	proprietary software
哲思	zeuux
许可证	license
发行版	distribution

注意事项

在撰写文档的时候，要采用书面用语。
在翻译文档的时候，要忠于原文，对于核心词汇，要同时给出原文，在翻译到本地语言的时候，力求符合本地语言的习惯。
在文章里，要给出引用的“参考资料”。
对于见习期的文档开发者，在增加文档文件的时候，需要事前与导师确认。

哲思源代码编写规范

Python编码规范

缩进

使用4个空格作为第一级缩进。

TAB或空格

不要混合TAB和空格。

最大行长度

最大行长度限制在80个字符内。

空白行

分割顶层函数和类定义使用二个空行。在类里面的方法定义用一个空行分割。多余的空行用来分割相关的函数组。使用空行分割逻辑块。

语句或表达式里面的空格

x = 1
y = 2

注释

注释最好写英文。与代码相违背的注释还不如没有注释。如果注释是一个句子，首字母要大写。在注释一个句子结束出加上二个空格。

块注释

通过一个#开始,#结束

内部注释

文档

所有的函数和模块都应该有文档，样例如下：

def kos_root():
    """Return the pathname of the KOS root directory."""
    global _kos_root
    if _kos_root: return _kos_root
    ...

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    Keyword arguments:
    real -- the real part (default 0.0)
    imag -- the imaginary part (default 0.0)

    """
    if imag == 0.0 and real == 0.0: return complex_zero
    ...

版本信息

需要加入源代码的版本信息，可以写下面的代码：

__version__ = "$Revision: 6104 $"
# $Source$

这段代码加在模块文档之后。

模块

模块命名使用小写，因为模块对应文件名，这样和文件的命名规范相一致。