Feathers:coding-conventions

原文地址：http://wiki.starling-framework.org/feathers/coding-conventions

Feathers 贡献者编程规范

本文档目前给出一个概要的说明，以后可能会增加更多内容。写到这里时，Feathers的源码并没有完全地遵从如下所述的规则。当Feathers日趋稳定时，将会朝这个方向努力。为了保持较快的开发进程，并没有那么严格地遵从该规范。而本项目外部的贡献者却可能持有一个更高的标准。

下面所用的public和private具有其原本的含义。当指定public或private访问控制符，将具有明确的含义。当没有访问控制符指定时，public所修饰的API暴露给该类的使用者。这也包含可以在派生类中访问的public成员和protected成员的情形。同样，private所修饰的方法仅仅在内部生效。内部API可能是protected访问控制的一部分，但是使用这些API将要自行承担风险。

空格

• 使用空格，而不是Tab；
• 在这些二元操作符两边逗留空格： +, -, *, /, ?, :, <, >, ==, 等等；
• 在这些关键字后边紧跟左括弧： if/for/while/等等——而不在中间留空格；
• 方法之间应该留一个空行。

超长行

• 保持每行字符数<=80。如果一条语句超过80字符，则应该在超过80之前打断，放到新的一行，并且对这些打断的行进行缩进排版，以保持代码整洁。
• 判断条件复杂的if语句应当用括弧清楚表明运算优先级并进行适当的断行，以保持可读性。另外把其中某些部分整合为变量体现可能会更显优雅。

花括号

• 所有的左花括弧{都应当新起一行，并且所有花括弧不应当放到行尾；
• 所有的if/for/while和其他结构的语句体都要确保使用花括号——即便语法上允许单行语句体可以省略花括号也要这样做！

命名

• 命名应当具有自注释性并保持清晰，极端简化是很不推荐的；
• 如果某个API跟Apache Flex或Adobe的fl.*某个组件作用类似的话，那么建议在Feathers中就使用相同的名称；
• 命名应当少用缩写，但普遍公认的首字母缩写词通常是可以接受的——这种情况需要保持每个字母的大写；
• 类命名使用驼峰命名法，就像这样：CamelCaseNames，并且必须用大写字母起头；
• 变量和函数名也使用驼峰命名法，类似：camelCaseNames，并且必须用小写字母起头；
• 无论怎样，私有成员变量应当以一个下划线_起头。

访问权限控制

• 通常，属性和方法应该是public或protected。使用private是不建议的因为这样限制了开发者扩展组件功能。
• 自定义名称空间强烈不推荐使用！

类结构整理

一般来说，类内部的定义应该组织如下：

 - 静态 变量
 - 静态 函数
 - 构造函数
 - 成员变量及其属性
 - public成员函数
 - protected成员函数
 - private成员函数

组织类的补充说明

• 共有的 getters 和 setters 应该紧跟在它们所暴露的似有变量后边。
• 通常，在同一种访问控制的方法定义区间(比如public或protected), 应当首先是覆盖方法，然后是本类的新方法，再后边是事件侦听处理函数。假如既有事件侦听处理函数，也有信号侦听处理函数的话，信号侦听处理函数应该放在事件侦听处理函数前边。
• 类似地，静态方法应当跟成员方法按同样的顺序布局。

this关键字

this关键字应该用于引用成员变量和函数。作者特别认真地贯彻这一原则，当你浏览Feathers源码时将会注意到这一点！

文档

• 所有的公有API都需要加ASDoc 注释；
• 标记私有函数为@private以使其在ASDoc生成文档时被忽略。如果需要，它们仍可以包含一个说明，但这仅仅在源码中能看到；
• 在你的说明种，当指向特定的类、变量、属性或方法时要使用标签；
• 当你指向其他公用API或类时，考虑添加一个@see标签；
• 当指向某种度量值（比如尺寸或时间）时，//必须//带上单位，比如像素或秒。

---

翻译者：王建文