При разработке плагинов, хелперов для Template CMS необходимо придерживаться правил и рекомендаций изложенных в этой статье.

PHP

1. Отступы

Все вложенные конструкции должны иметь отступ от родителя на 4 символа.

Для оформления отступов в исходном коде может использоваться табуляция размером 4 пробела.

    for ($j = 1; $j < 5; $j++) {
        for ($j = 1; $j < 5; $j++) { 
            doSomething(); 
        }
    } 

2. Расстановка скобок.

Unix-стиль расстановки скобок.

Открывающая скобка остается на предыдущей строке, закрывающаяся находится под первым символом блока. Вложенные блок сдвинут на один отступ.

    if ((condition1) || (condition2)) {
        action1;
    } elseif ((condition3) && (condition4)) {
        action2; 
    } else {
        defaultaction; 
    } 

ОБЯЗАТЕЛЬНО использовать ВСЕГДА фигурные скобки даже в ситуациях, где они технически необязательны. Имея их, увеличивается читабельность и уменьшается вероятность логических ошибок, которые могут появиться при добавлении новых строк.

3. Выбор имен

Все имена должны нести какой-то смысл и быть словами английского языка.

3.1 Переменные

Имена переменных начинаются со строчной буквы. Слова разделяются знаками подчеркивания.

Одно/двухбуквенные имена должны использоваться только в случае крайней необходимости и обязательным комментированием назначения. Исключение составляют лишь счетчики циклов.

Переменная должна использоваться целенаправленно. Т.е. если переменная $temp используется как буфер при чтении из файла, то она не должна использоваться в той же функции как счетчик в массиве.

3.2 Функции

Имена функций/методов класса в стиле lowerCamelCase

3.4 Классы

Названия классов в стиле CamelCase.

3.5 Константы

Константы должны быть всегда написаны в верхнем регистре с подчеркиванием для разделения слов.

3.5 Названия файлов и папок

Названия файлов в стиле СamelCase. Названия папок должны состоять из строчных букв, отдельные слова разделяются знаком подчеркивания.

4. Комментирование кода

Исходный код должен быть прокомментирован для удобства последующего использования. Комментарии писать только на английском языке, никаких русских, украинских, белорусских и пр. языках комментариев!

4.1 Заголовки файлов

Каждый файл должен содержать заголовок формата phpDocumentor

     /** 
      * Files manager plugin 
      * @package TemplateCMS 
      * @subpackage Plugins 
      * @author Romanenko Sergey / Awilum 
      * @copyright 2010 Romanenko Sergey / Awilum 
      * @version 1.0 
      */ 

4.2 Заголовки классов

Каждый класс должен содержать заголовок формата phpDocumentor

     /**
      * The first example class, this is in the same package as the 
      * procedural stuff in the start of the file 
      * @package sample * @subpackage classes
      */ 
      class MyClass {
    
      } 

4.3 Заголовки функций/методов

Каждая функция должна содержать заголовок формата phpDocumentor

     /** 
      * Parse BBC
      * @param string $text text with bbc tags
      * @return string $text 
      */ 
      function parseBBC($text) {
         
      } 

4.4 Внутренние комментарии

Остальной код программы должен быть прокомментирован согласно потребностям. Обязательным является комментирование отдельных логических блоков. Блоки в которым необходимо вернуться для дальнейшего рассмотрения необходимо помечать phpDoc тегом @todo

CSS

1. Расстановка скобок и отступы

При расстановке скобок и отступах применять правила приведенные выше для PHP. Пример правильного CSS блока:

     #header-wrapper {
         background-color: #333;
         width:100%;
     }

2. Селекторы

Необходимо давать осмысленные имена селекторам и писать их в нижнем регистре. Название из нескольких слов разделять дефисом - смотреть пример выше.

3. Свойства и значения

Свойства должны быть упорядочены в алфавитном порядке по возрастанию. Цвета задавать в #HEX. (в нижнем регистре)

     #header-title {
         color: #fff; 
	 font-size: 44px; 
         font-weight: bold; 
         padding-top: 10px;
         padding-bottom: 10px; 
         text-shadow: 1px 0 2px #4d4d4d; 
      } 

blog comments powered by Disqus