Стандарты кодирования
Общее редактирование кода
используйте только пробелы для идентации кода вместо табуляторов, во всех современных редакторах есть функция замены табуляторов пробелами(скажем, в 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
Обсуждение