Combodo编码标准

此页面是iTop编码约定的简要说明(主要用于PHP)。 iTop编码约定与PSR-2标准,但也要注意很多重要的区别!

源代码文件以UTF-8编码(没有BOM在文件的开头)。
换行符必须为Lf。

PHP文件必须在文件<?php的开头使用长PHP开头的标签,但不得包含任何关闭标签的PHP。这样可以防止在文件末尾错误地添加多余的空白字符,这些空白字符将被附加到页面生成的标签上。

一个编辑器配置 文件可用在iTop存储库中.

在iTop中,所有代码均以英语编写:函数,变量,类名和注释均应以有效的英语编写。

字符串定界符

您可以使用任何喜欢的定界符,主要目的是保持代码可读性。

使用时heredoc / nowdoc,我们建议使用分隔符JetBrains的语言注入.

例子 :

$sHtml = '<a href="http://www.combodo.com">';
 
$sFooBarBaz = "{$foo}-{$bar} {$baz}";
 
$sJs = <<<JS
console.debug("this is some JS code");
console.debug("having the right delimiter keyword will help language injection !");
JS;

变量命名

变量,职能参数和对象属性使用混合大小写约定命名(即所有小写字母,每个单词开头都有大写字母)和用作类型提示的前缀字母:

  • 一个前缀用于哈希或数组(PHP没有任何区别:每个数组实际上是一个哈希)
  • i前缀用于整数
  • o前缀用于PHP对象
  • s前缀用于字符串
  • 很少使用:f表示浮点数(即非整数),r或h可用于资源句柄。

例:

<?php
 
$iCount = 1;
$sText = 'This is a text';
$oPage = new WebPage('test');
$fRank = 1.25;
$hDir = ('/opt');
 
// No PHP closing tag

没有前缀的变量应该是混合类型(可以是字符串,数组或对象)

例:

public function Set($sAttCode, $value) { ... }

允许的例外

  • 用于循环计数器的局部变量(例如$ i,$ j)可能没有前缀。
  • 在涉及大量数字变量的数学计算中,可以删除此类变量的前缀(例如$ x,$ y,$ xMax…)是可以接受的
  • 由于历史原因,WebPage类(及相关类)以及MetaModel中的某些部分使用不同的约定:变量均为小写字母,并带有下划线字符以分隔单词。对象属性(成员)使用m_前缀作为前缀。

功能命名

函数和对象方法使用混合大小写约定命名(即所有小写字母,每个单词开头均带有大写字母)。即使PHP对职能的名称不区分大小写,这也有助于区分项目的功能与通常用小写形式编写的PHP内置功能。职能名称通常基于表示正在执行的职能的动词。

例:

function DisplayWelcomePopup(WebPage $oP) {
    // Code goes here
}

关于可视化和其他关键字顺序,PSR-2状态 :

可视化必须在所有属性和方法上声明;摘要和最终结果必须在可视化之前声明;必须在可视化之后声明静态。

空格和缩进

自 2020 年 8 月 28 日以来,此约定已更改。基本代码将随时更新(由于错误/增强原因修改时按函数函数)。

缩进使用制表符(将编辑器配置为将制表符显示为4个字符宽)

开括号(对于classes, functions, if/else, try/catch, switch)必须放在下一行,闭括号必须在正文之后的下一行。闭合支架必须与相应的开口支架垂直对齐。

例:

class NiceWebPage extends WebPage { ... public function SetContentType($sContentType) { if($sContentType == '') { // Do something } else { // Do something different } } }

编写职能调用时,在职能名称后紧跟在括号之间提供的参数:职能名称与参数列表之间没有空格。每个参数列表中的逗号后跟一个空格。

例:

$sValue = Utils::ReadParam('param1', 'default_value');

二进制运算符(==,+,&&)被空格包围。

例外:串联运算符。不被空格包围,因为当使用非比例字体时,这倾向于使行更紧凑,并且不会降低代码的可读性。

例:

if (($aPerson[$this->iPersonId][0]) && ($aPerson[$this->iPersonId][0] != "")) { if ($this->sSynchronizeOrganization == 'yes') { $sName = $aPerson[$this->iPersonId]['first_name'].' '.$aPerson[$this->iPersonId]['last_name']; } }

php文件

存储库本身描述了编写PhpDoc的规则:请参阅/.doc/README.md.

词典条目

这本身就是一个主题,请参见专用的Wiki页面:如何翻译

原文:https://www.itophub.io/wiki/page?id=2_6_0%3Acustomization%3Acoding_standards


Combodo Coding Standards

This page is a brief description of the iTop coding conventions (mostly for PHP). The iTop coding conventions share a lot with the PSR-2 standard, but there are also quite a few significant differences, beware!

The source code files are encoded in UTF-8 (without a BOM at the beginning of the file).
The line feeds must be Lf.

PHP files must use the long PHP opening tag at the beginning of the file <?php but must not contain any PHP closing tag. This prevents extra blank characters to be added by mistake at the end of the file… where they will be appended to the output produced by the page.

An Editor config file is available in the iTop repository.

In iTop, all the code is written in English: functions, variables, class names and comments are to be written in valid English.

Strings delimiter

You can use any of the delimiter you prefer, the main goal is to keep the code readable.

When using heredoc / nowdoc, we recommend using delimiters that allows JetBrains' language injection.

Examples :

$sHtml = '<a href="http://www.combodo.com">';
 
$sFooBarBaz = "{$foo}-{$bar} {$baz}";
 
$sJs = <<<JS
console.debug("this is some JS code");
console.debug("having the right delimiter keyword will help language injection !");
JS;

Variables naming

Variables, function parameters and object properties are named using a mixed case convention (i.e. all lowercase with an uppercase letter at the beginning of each word) and a prefix letter used as a type hint:

  • the a prefix is used for hash or arrays (PHP does not make any difference: each array is actually a hash)

  • the i prefix is used of for integers

  • the o prefix is used for PHP objects

  • the s prefix is used for strings

  • more rarely used: f for floating point numbers (i.e. non integer numbers), r or h can be used for resource handles.

Example:

<?php
 
$iCount = 1;
$sText = 'This is a text';
$oPage = new WebPage('test');
$fRank = 1.25;
$hDir = ('/opt');
 
// No PHP closing tag

A variable with no prefix is supposed to be of mixed type (can be either a string, an array or an object)

Example:

public function Set($sAttCode, $value) { ... }

Allowed Exceptions

  • Local variables used for loop counters (e.g. $i, $j) may have no prefix.

  • In mathematical computations involving a lot of numeric variables it is acceptable to drop the prefix for such variables (e.g. $x, $y, $xMax…)

  • For historical reasons, the WebPage class (and the related classes) as well as some parts inside MetaModel use a different convention: variables are all lowercase with an underscore character to separate words. Object properties (members) are prefixed using the m_ prefix.

Functions naming

Functions and object methods are named using a mixed case convention (i.e. all lowercase with an uppercase letter at the beginning of each word). Even if PHP is not case sensitive for the function names, this useful to distinguish the functions which are part of the project from PHP's built-in functions which are generally written in lowercase. The function names are generally based on a verb expressing the action being performed.

Example:

function DisplayWelcomePopup(WebPage $oP) { // Code goes here }

Regarding visibility and other keywords order, the PSR-2 states :

Visibility MUST be declared on all properties and methods; abstract and final MUST be declared before the visibility; static MUST be declared after the visibility.

White spaces and indentation

The indentation is made using tabulations (configure your editor to display a tabs as 4 characters wide)

Opening braces (for classes, functions, if/else, try/catch, switch) must go on the next line, and closing braces must go on the next line after the body. The closing brace must be vertically aligned with the corresponding opening brace.

Example:

class NiceWebPage extends WebPage { ... public function SetContentType($sContentType) { if($sContentType == '') { // Do something } else { // Do something different } } }

When writing function calls, the arguments supplied (between parentheses) immediately after the name of the function: there is no space between the function name and the arguments list. The comma in each arguments list is followed by a space.

Example:

$sValue = Utils::ReadParam('param1', 'default_value');

The binary operators (==, +, &&) are surrounded by spaces.

Exception: the concatenation operator . is not surrounded by spaces since this tends to keep lines more compact and does not reduce the readability of the code when using non-proportional fonts.

Example:

if (($aPerson[$this->iPersonId][0]) && ($aPerson[$this->iPersonId][0] != "")) { if ($this->sSynchronizeOrganization == 'yes') { $sName = $aPerson[$this->iPersonId]['first_name'].' '.$aPerson[$this->iPersonId]['last_name']; } }

PhpDoc

The rules to write PhpDoc are described in the repository itself : see /.doc/README.md.

Dictionnaries entries

This is a subject by itself, see the dedicated wiki page : How to translate

 

标签:
由 superadmin 在 2020/08/27, 16:32 创建
    

需要帮助?

如果您需要有关XWiki的帮助,可以联系:

深圳市艾拓先锋企业管理咨询有限公司