SimSym

NewVision WEB-development Team Blog

Стандарты Кодирования

Выкладываем основную часть стандартов кодирования, которые выработала наша команда на ретроспективах.

База данных

Именование полей

  • для полей с датами используем окончание _at, например: last_checked_at
  • для логических полей (boolean: true/false) исползуем приставку is_, например is_active
  • при использовании составных имен в начале указываем «главную сущность», затем ее характеристику. По сути аналогичное правило применяется и для названия переменных, классов, файлов и т.п. Такое правило упрощает читабельность и сортировку. Т.к. схожие сущности группируются вместе
    • #INCORRECT
    input_link_id
    output_link_id

    #CORRECT
    link_id_input
    link_id_output

Кодирование

общее

  • не использовать символ табуляции. В качестве табуляции использовать 2 пробела.
  • используемая кодировка: UTF-8
  • в начале файла и во вставках php кода в шаблонах использовать <?php
  • в файлах с кодом не вставлять закрывающий ‘?>’
  • открывающие и закрывающие фигурные скобки находятся на своих отдельных строках

стандарты именования

  • если переменная ( или индекс массива) несет булевое значение то она должна иметь приставку is/has/do и т.п.
  • если переменная обозначает дату, то можно использовать приставку at
  • использовать CamelCase стиль именования для названия классов проекта. Если класс относится к какому-либо независимому модулю, то аббревиатура модуля пишется маленькими символами перед названием:
    class MakeCoffee {...}
    class sfCamelCase {...}
  • использовать camelCase стиль именования для свойств и методов класса
    class MakeCoffee
    {
      protected $coffeeTimer;
      function makeCoffee()
      {
        $this->coffeeTimer = 5;
      }
    }
  • использовать подчеркивание «_» для именования:
    • индексов массива
    • локальных переменных, параметров методов класса и функций
      class MakeCoffee
      {
        function makeCoffee($cnt_sugar, $cnt_whater)
        {
          $cooking_time = $cnt_sugar * $cnt_whater
        }
      }
    • функций вне класса, также функции вне класса пишутся с маленькой буквы

      function parse_url($url, $parser_params)
      {
        ...
      }
    • опций/параметров в конфигах

      #test.yml
        all:
          some_config: value
          some_params: value
  • модули именуем с использованием символа подчеркивания

    modules/user_office/...
    modules/operation_data_account/...
    modules/master_step/...

Пробелы

Использовать пробелы в:

  • в операции присваивания после и перед символом =
  • конкатенация строк
  • после запятой
  • операторы в арифметических выражениях отделяются пробелами
  • после управляющих структур ( if, forearch, switch, catch …)

Выравнивание

  • в случае переноса длинного sql на новую строчку – используем одну табуляцию ( два пробела)
    $test_query = Doctrine_Query::create()
      ->from('result r')
      ->leftJoin('s.sector s');
  • в случае переноса большого числа параметров на новую строчку – выравниваем их относительно скобки ( первых параметров)
    $res = $this->saveResults($param1, $param2, $param3
                              $param4, $param5);
  • в случае подряд идущих строк с однотипными операциями ( например присваивания или инициализация) выравниваем их относительно оператора
    $var1     = 1;
    $somevar  = 4;
    $testvar2 = 2;
  • в случае больших массивов, выравниваем так:
    url_for(array(
      'module'   => 'job',
      'action'   => 'show',
      'test_arr' => array(
        'some'   => 'some',
        'secodn' => 'second'
      ),
      'id'       => $job->getId(),
      'company'  => $job->getCompany()
    ))

Примеры кода

Declarations

class MyClass implements I0, I1, I2
{
}
class MyClass
{
  // если объявляем свойства класса в одну строку
  public $a = 0, $b = 1, $c = 2, $d = 3;
  const MY_TRUE = 1, MY_FALSE = 2;

  // но лучше объявлять каждое свойство с новой строки
  public $a = 0;
  public $b = 1;

  const CONST_TRUE  = 1;
  const CONST_FALSE = 2;
}
function foo()
{
}
function bar(MyClass $x, $y, $z = 1)
{
}

Control statements

$a = 4;
foo();
bar($x, $y);
if (true)
{
  return 1;
}
else if (true)
{
  return 3;
}
else
{
  return 2;
}

try
{
  echo $b;
}
catch (Exception $e)
{
}

if ($condition)
{
  return $foo;
}
else
{
  return $bar;
}

for ($i = 0, $j = 0; $i < 8; $i ++, $j --)
{
}

foreach ($s as $key => $value)
{
}

switch ($number)
{
  case RED:
    return GREEN;
  case GREEN:
    return BLUE;
  case BLUE:
    return RED;
  default:
    return BLACK;
}

while ($condition)
{
}

do
{
}
while ($condition);

static $a, $b;
global $a, $b;

Документирование

Документацию пишем на русском языке. Соответственно, среда должна быть настроена на кодировку UTF-8.
Документированию подлежат:

  • Файл – блок документации в начале файла, если в файле хранится только один класс, то его документации будет достаточно
  • Класс – блок документации перед классом
  • Функция или метод класса – блок документации перед функцией/методом, так же необходимо указать
    • входящие параметры
    • возвращаемые значения
  • Переменные класса – если их значение не тривиально

Автор:Ruslan Kovalenko Дата: Май 21, 2010 | Категория: Команда

Один комментарий

Tratatun  on Июнь 11th, 2010

здесь ничего не сказано о ваших стандартах именования файлов, опишите их пожалуйста

Оставить комментарий