Joomla! 编码规范
内联代码注释
关于
编码规范
客户端语法风格指南
附录
本章详细介绍了内联代码注释。内联注释是指所有不包含在文档块中的注释。内联注释的目的是解释代码上下文。这种解释可以采用多种不同的形式。
鼓励使用易读且叙述性的风格编写注释，尤其是在解释复杂流程时。一般来说，注释应该放置在解释的代码附近，而不是在整个代码块之前。
注释应尽可能像句子一样，也就是说，注释应完整且可读，而不是使用简写。
注释不能替代详细的文档块。注释用于解释代码本身的逻辑和结构，而不是代码的使用方法。
注释格式
引入大段代码且超过两行的注释块应使用/* */（C）风格，并且应在每行使用*，并遵循与文档块相同的空格/制表符规则。如果需要一个大型的介绍，请考虑是否应该将此块分离到一个方法中以减少复杂性，从而提供一个完整的文档块。
注释应位于其引用的代码之前。作为推论，注释不应与引用的代码位于同一行（这会将它们放在其引用的代码之后）。它们应该在自己的行上。
不要在注释与其引用的代码之间留空行（注释块下方没有空格）。
在注释或注释块之前始终留一个空行，除非注释（或块）位于代码结构的开头。（在“{”行之后不应有空行）
例如，在以下情况下，第一个注释之前没有新行（因为它跟随“{”行），但我们确实希望在第二个注释之前有一个新行
while (!$done)
{
// We don't want an infinite loop here.
$done = true;
}
// Now let's do something interesting.
$result = somethingInteresting();注释应与引用的代码对齐，使用与注释后一行相同的缩进。
注释应使用制表符缩进（像代码一样，而不是像文档块一样）。
注释内容
注释应使用英式英语（en-GB）。
在 // 和注释文本的开头之间始终留一个空格。
新行应始终以大写字母开头，除非
- 该行是完整句子的延续。
- 该术语是代码且区分大小写。
专门为了确保与其他软件兼容而包含的代码（例如特定浏览器或特定版本的 CMS 或出于向后兼容性的原因）应明确标记为这样。如果打算在将来删除特定代码，请说明，但不要使用弃用标记或指定版本（这很难预测）。
检查所有注释的拼写和语法（参见下文和英式英语指南）。
仅当它是完整句子时，才以句号结束一行。
如果合适，请使用 See:、Link: 和 Note: 作为注释，而不是使用文档块标记。
除非与注释内容特别相关，否则不要在注释中使用 HTML。
除非有明确说明的原因，否则不要保留注释掉的代码。在这种情况下，一条“代码有意注释”的注释将防止意外删除。
注释可能包含有关将来如何扩展或修改某些内容的前瞻性陈述，但不包含指示代码不完整或未准备好使用的待办事项。
请记住，幽默和讽刺很难翻译。
首字母缩略词
首字母缩略词（如 HTML、XML、SQL、GMT 和 UTC）的所有字母都应大写。
需要检查的常见拼写和语法错误。
Joomla 贡献者包括许多非英语母语人士，因此出现拼写和语法错误是可以理解的。同时，一些阅读注释的人也是非英语母语人士，甚至可能使用机器翻译来理解注释。这使得注释必须遵循正确的英式英语拼写和语法规则变得非常重要。不幸的是，这些规则可能很棘手。
S 与 Z
英式英语最常用ise，而美式英语则使用ize，例如使用normalise而不是normalize。（请注意，此规则有一些例外。）
撇号的使用是英语中最棘手的部分之一。
Lets 与 let’s
Lets 表示允许或准许。
// This lets the user enter dataLet’s 是 let us 的缩写，表示我们现在要这样做。
// Let's validate the fieldIts 与 it’s
Its 是 it 的所有格形式。
// Get its IDIt’s 是 it is 的缩写。
// It's time to save一些常用单词的正确 Joomla 拼写。
- dependant
- deprecated