Месяц назад я вступил в должность ИТ директора, проработав до этого пару лет старшим программистом. Наша контора большей частью пишет на php, каждый пишет как попало и без единого стиля, можно узнавать автора даже не читая копирайтов, что особенно неприятно когда приходит новый программист в команду.
Как ИТ директора, первое мое решение — ввести строгие правила регламентации кода, для этого создаю тему, где предлагаю обсудить наиболее удобные варианты, начальным списком пишу правила используемые лично мной.
Имена файлов классов и самих классов
Имя файла класса должно быть идентично имени класса содержащегося в нем, название класса пишется с большой буквы без префиксов
пример:
класc — class Foo
файл — Foo.php
класc – Namespace/class Foo
файл — Foo.php
в отдельных случаях допускается использование суффиксов
пример:
класc- Foo
файл — Foo.class.php
класc модели — Foo
файл — Foo.model.php
рекомендуется первый способ, и не рекомендуется складывать классы разного назначения вместе, например компоненты и модели должны лежать раздельно, а не отделяться разными суффиксами. Для избегания совпадений имен классов используйте неймспейсы
Оформление кода
Для оформления отступов кода используют табуляции, фигурные скобки ставят по типу стиля Олмана.
пример:
class Foo { private $bar public function bar() { return $this->bar; } } Для одно строчных вложений фигурные скобки не ставят.
пример:
If($bar === false) return true; else { $bar = new Foo; return $bar; } Между логически не связанными конструкциями ставят пустую строку.
пример:
$paramList = array(); foreach($varibleList as $val) $paramList[] = $val; If(empty($paramList)) return false; пояснение: в данном случае $paramList имеет явное отношение к логике внутри foreach
В файлах классов, закрывающий оператор ?> не ставят
Между двумя функциями класса ставят две пустые строки, между свойством класса, и функцией класса имеющих прямую связь ставят одну строку, это создает визуальную привязку
пример:
private static $instance; public static function getInstance() { if ( is_null(self::$instance) ) self::$instance = new self; return self::$instance; } public function appStart() { ........ } Именование переменных и функций
переменные и функции своим названием отображать свою суть. Название должно состоять не более чем из четырех слов, не считая префикса и пишется с маленькой буквы, слова разделены заглавными буквами, использование нижних подчеркиваний только когда этого требует код. Допускается использование распространенных сокращений, когда их смысл прозрачен для текущей ситуации. Аббревиатуры пишутся как обычные слова. Не рекомендуется использование цифр в названии
пример:
public function getFullName($userId) { $fullName = "{$this->firstName} {$this->lastName}"; return $fullName; } пример2:
public function getHtmlTagA($uri, $content) { $htmlTagA = "<a href=\"{$uri}\">{$content}</a>" return $htmlTagA; } Префиксы используются для обозначения действия, кроме ситуаций когда функция обозначает реализацию конкретной структуры. Например getProfile($userId) обозначает получения профиля юзера по его Id, в тоже время profile($userId) подразумевает сам профиль как логически завершенную структуру, так например в getProfile($userId) можно получить имя и фамилию пользователя, а потом превратить их в полное имя, profile($userId) же содержит готовую функцию получения полного имени. Это различие не функциональное, этим различием программист показывает как по его задумке будет использоваться данная функция, как завершенная логика, или как поставщик сырых данных для другой логики. В случаях когда структура подходит под оба варианта — следует использовать префикс.
Списки стандартных префиксов:
get — получить
set — установить
is — проверить является ли
count — количество
Суффиксы используются для обозначения типа данных в переменной, использование суффиксов не является обязательным, но довольно удобно в некоторых ситуациях
пример:
$paramList = array(); Для установки флагов рекомендуется использование констант
пример:
const GET_CURRENT_USER_ID = false; public function getProfile($userId = self::GET_CURRENT_USER_ID) { if($userId === self::GET_CURRENT_USER_ID) $userId = App::getObj()->currentUserId; ...... } При сложении строк из переменных должны использоваться вставки переменных в строку обрамленную двойными кавычками, при этом переменные дополнительно обрамляться фигурными скобками. Строки не содержавшие переменных обрамляются одинарными кавычками
пример:
$userAge = 18 $userZodiacSumbol = 'телец'; $ageStatusString = "{$userAge} {$userZodiacSumbol}"; правила записи массивов
массивы пишутся согласно стиля K&R, для разделения слов в ключей массива используют нижнее подчеркивание, кроме ситуаций когда логика требует иначе
пример:
$locationList = array( 'rus' => array( 'name' => 'Россия', 'original_name' => 'Россия', ), 'usa' => array( 'name' => 'Америка', 'original_name' => 'USA', ), ); правила комментирования кода
все комментарии оформляться согласно PHPDoc, наличие комментариев к методам и свойствам класса обязательно.
Каждый класс должен иметь указания версии с номером версии и датой
пример:
@version 1.2 (2013/03/14)
помимо этого обязательно указание рабочих контактов автора и MIT лицензии
@license http://www.opensource.org/licenses/mit-license.php MIT License
@author Name Family <name@domain.net>
ссылка на оригинал статьи http://habrahabr.ru/post/173299/
Добавить комментарий