limb3_2007_2:ru:coding_standards
Содержание
Стандарты кодирования
Общее редактирование кода
- используйте только пробелы для идентации кода вместо табуляторов, во всех современных редакторах есть функция замены табуляторов пробелами(скажем, в JEdit эта опция называется soft tabs)
- один табулятор равен 2(двум) пробелам(к примеру, в JEdit, Tab width = 2, Indent Width = 2)
Языковые конструкции
Операторы
- все операторы(кроме инкрементных) разделяются одиночным пробелом:
$a = 1, но не $a=1; однако $i++ - после управляющей конструкции(if, for, etc) не следует использовать пробелы перед скобкой и внутри скобок:
if($a == 1), но не if ( $a == 1 ) - если после управляющих конструкций следует однострочная операция, {} можно не использовать
Идентация, новые строка и проч.
- изначально код имеет нулевое смещение относительно левого края
- {…} используются с новой строки без исключения
- код в блоках внутри {…} имеет идентацию на один уровень вправо относительно {}
- старайтесь группировать несколько схожих операций в безинтервальные блоки
- логически сгруппированные блоки отделяются символом новой строки
Функции, переменные, классы, методы и проч.
Названия
- для названий классов следует использовать формат MyClassName:
class MyClassName{}, но не my_class_name - для названий функций/методов следует использовать формат methodName:
function methodName(){} - переменные/аттрибуты могут иметь название $varName либо $var_name, и хотя это не принципиально, мы все же склоняемся к использованию $var_name
Уровни доступа(public/protected/private)
Т.к Limb3 изначально разрабатывался для PHP4, после перехода на PHP5 не вся кодовая база использует правильные уровни доступа, однако эта ситуация будет постепенно исправлена в последующих релизах. Небольшие рекомендации насчет использования уровней доступа:
- ключевое слово public обычно опускается для методов, т.к оно нам кажется излишним
- уровень доступа private не используется вообще, т.к может усложнять тестирование в определенных случаях, рекомендуется использовать уровень доступа protected
- закрытые(protected) методы обычно отмечаются начальным символом «_»:
protected function _doThisPrivately(){}. Не все методы, имеющие такое название, имеют уровень доступа protected на данный момент, постепенно это будет исправлено - всем аттрибутам рекомендуется ставить уровень доступа protected
- на данный момент все аттрибуты не имеют уровня доступа вообще(используется var), однако в дальнейшем будет использован уровень доступа protected
- уровень доступа final рекомендуется использовать только в крайних случаях, когда в этом есть уверенность на 10000%(final может представлять трудности во время тестирования).
TypeHints
На данный момент не рекомендуется пользоваться typehints вообще, т.к мок объекты SimpleTest 1.x конфликтуют с ними. Однако с выходом SimpleTest2 данная ситуация будет исправлена и использование typehints будет приветствоваться.
Включения PHP исходных файлов
- константы, которые используются для физического указания расположения библиотек обычно имеют окончание _DIR:
define('APP_DIR', '/some/path/'); - обычно мы используем include* внутри функций, а require* в глобальном namespace
Комментарии
- комментарии мы почти пока не делаем, ибо хороший код обычно говорит сам за себя и к тому же есть тесты(в будущем однако возможно появятся небольшие комментарии для phpDocumentor)
- комментарии обычно уместны в тех местах кода, который пока еще не подвергался рефакторингу и поэтому его «читабельность» затруднена
- также комментарии бывают исключительно полезны в тестах, где с их помощью можно сделать акцент на тонкости тестирования:
Лицензия
- лицензионная «шапка» для кода(обычно в редакторе можно настроить систему шаблонов и вызывать шаблоны один кликом):
/********************************************************************************** * Copyright 2004 BIT, Ltd. http://limb-project.com, mailto: support@limb-project.com * * Released under the LGPL license (http://www.gnu.org/copyleft/lesser.html) *********************************************************************************** * * $Id$ * ***********************************************************************************/
Пример кода
/********************************************************************************** * Copyright 2004 BIT, Ltd. http://limb-project.com, mailto: support@limb-project.com * * Released under the LGPL license (http://www.gnu.org/copyleft/lesser.html) *********************************************************************************** * * $Id$ * ***********************************************************************************/ require_once(SOME_DIR . '/Foo.class.php'); //класс class FooClass { //аттрибуты protected $foo_name; protected $request; //конструктор function FooClass($request) { $this->request = $request; $this->foo_name = 'Foo'; } protected function _createBar() { iclude_once(SOME_DIR . '/Bar.class.php'); return new Bar(); } //метод function doIt() { if($this->foo_name == 'Bar') { $res = globalDoIt(); echo $res; } //для простых управляющих конструкций {} можно опускать if($this->foo_name == 'Test') return; //логически сгруппированный блок кода $db = getDbConnection(); $it = $db->exec('select * from a'); foreach($it as $record) echo $record->get('id'); $i++; } } //функция function globalDoIt() { $some_var = 1; return 1; }
Расположение кода в файловой системе
- один класс = один файл, тоже самое относится к интерфейсам
- все файлы с классами имеют case sensitive название: ClassName.class.php, где ClassName название класса, а расширение .class.php указывает на то, что это класс
- тоже самое относится к интерфейсам, с небольшими изменениями: Doable.interface.php, где Doable название интерфейса, а расширение .interface.php указывает на то, что это интерфейс
- подключаемый модуль имеет расширение .inc.php
- исполняемый скрипт обычно имеет расширение .php(здесь есть некоторые исключения из правила, скажем, setup.php, который не является самостоятельным исполняющимся скриптом)
- тесты для одного класса обычно имеют такое же название, что и сам класс + окончание Test, т.е MyClassTest
- тесты обычно имеют паралельную структуру с основным кодом, т.е /src/util/lmbComplexArray.class.php ⇒ /cases/util/ComplexArrayTest.class.php
limb3_2007_2/ru/coding_standards.txt · Последнее изменение: 2010/11/10 10:02 — 127.0.0.1

Обсуждение