softmg / coding_rules

rules of coding in softmg company

Рекомендации по стилю для команды Soft Media Group.

Мотивация

Уважаемые коллеги, цел этого материала привить команде определенный единый стиль программирования.

• Зачем?: Чтобы мы все понимали код коллег без лишних действий.
• Зачем?: Чтобы внести изменения в код было проще (это важно!).

Список рекомендации

• early return

Early Return

• Что?: Ранний выход из функции|метода.
• Зачем?: Чтобы повысить читаемость кода.
• Зачем?: Чтобы было меньше вложенности.

Лучше если в начале метода сразу прописаны условия при которых он возвращает значение или бросает исключения.

Примеры:

// Плохо

function something() {
   if (expression) {
       //...
       //...
       //...
       //...
       //...
       //...
       //...
       //...
   } else {
       doSomething()
   }
}

// Хорошо

function something() {
   if (!expression) {
       doSomething()
       return;
   }
   
   //...
   //...
   //...
   //...
   //...
   //...
   //...
   //...
}

# Ужасно

function something1() {
   if (expression1) {
      //111
      //111
      
      if (expression2) {
          //222
          //222
          
          if (expression3) {
             //333
             //333
             if (expression4) {
                 //444
                 //444
                 
                 if (expression5) {
                     //555
                     //555
                     
                     if (expression6) {
                        //666
                     }
                 }
             } else {
                //777
                //777
             }
          }
      }
   }
}

# Хорошо

function something1() {
   if (!expression1) {
       return;
   }
   
   //111
   //111
   
   if (!expression2) {
       return;
   }
   
   //222
   //222
   
   if (!expression3) {
       return;
   }
   
   //333
   //333
   
   if (!expression4) {
       //777
       //777
      
       return;
   }
   
   //444
   //444
   
   if (!expression5) {
       return;
   }
   
   //555
   //555
   
   if (!expression6) {
       return;
   }
   
   //666
}

Phpstorm configs

• Должен соблюдаться следующий стиль кода PSR-2

• Для фреймворков используйте данный стиль кодирования, можно импортировать тут Берем отсюда Sofmg PSR-2.xml После импортирования можно отформатировать имеющийся код через пункт меню Code->Reformat Code (Ctrl+Alt+Z)

• Устанавливаем php code sniffer, который следит за стилем кода PSR-2 https://www.jetbrains.com/help/phpstorm/2016.3/using-php-code-sniffer-tool.html Пример его использования тут при наведении подсвечивает рекомендации по стилю кода.

Рекомендации по работе с git

• Смотрим тут

Документация

• В каждом проекте должна быть документация в корневом файле README.md с указанием особенностей проекта и информацией о разворачивании проекта
• В коде большинство функций должно быть документировано в стиле PHPDoc . Для быстрой генерации после написания каркаса функции (входные параметры + возвращаемый) набрать перед функцией /** и нажать enter

Рекомендации по Symfony

• Смотрим тут