Если вкратце, то египетские скобки, кемелКейс и смарт-табуляция (табы для отступов, пробелы для выравнивания).
Данные правила написания кода являются стандартом по умолчанию. Они используются, если в проекте или других стандартах, специфичных для языков, не оговорены иные правила.
На территории Sijeko царит стиль-дискриминация и формат-фашизм. При этом сохраняется разумность: правила не взяты с потолка, каждое из них имеет причины и свою предысторию. Общие стандарты по написанию кода, именованию файлов и прочему позволяют легче разбираться с существующими проектами даже новичкам.
Код должен выглядеть, как написанный одним человеком, независимо от того, сколько человек над ним работает.
Настройки делаются один раз после установки Идеи в диалоге настроек по умолчанию:
File → Default Settings
Если проект уже есть, можно настроить его отдельно:
File → Settings
В основном требуется настроить стиль кодирования и инспекции кода. Остальные настройки по умолчанию выставлены хорошо, можно изменять по вкусу.
Мы везде используем символы табуляции для отступов и подход смарт-табуляции. В окне настроек:
Editor → Code Style
проходим по всем языкам, выставляем везде одинаково:
Use tab character: Yes
Smart tabs: Yes
Tab size: 4
Indent: 4
Continuation indent: 4
При желании можно поставить во все три числовых поля числа 2 или 8, или сколько хотите (лишь бы числа были равны).
Файлы обязаны заканчиваться пустой строкой — это упрощает выделение текста мышкой от текущего места до конца файла. Также полезно в редакторе видеть пустые символы в конце строк. Ставим галочки:
Settings → Editor → General → Ensure line feed at file end on Save
Settings → Editor → General → Appearance → Show whitespaces и Trailing (две галочки)
Остальное в стилях кодирования по умолчанию в Идее стоит нормально: PSR-2 для PHP, нечто похожее для JavaScript и так далее.
Все инспекции, приведённые в этом разделе производятся при проталкивании изменений в наши репозитории. Если код не соответствует единому стандарту, коммиты не пройдут.
Удобным будет настроить инспекции прямо в среде разработки, чтобы не править стиль кодирования по сообщениям при коммитах: они не интерактивны (выдаются простым текстом) и могут занять очень много коммитов на исправление.
Если вы работаете с PHP-кодом и хотите включить PHP Code Sniffer, необходимо поставить в операционную систему PHP.
… … …
После этого:
Editor → Inspections → PHP → PHP Code Sniffer validation (поставить галочку)
ESLint — мощный инструмент для проверки яваскрипт-кода как на потенциальные ошибки программирования, так и на соответствие текста определённому стилю.
Ставим NodeJS и NPM.
Ставим ESLint:
sudo npm install -g eslint
Настраиваем инспекции в Идее (настройки среды по умолчанию):
File → Default Settings → Languages & Frameworks → JavaScript → Code Quality Tools → ESLint
Там галочки и путь к файлу настроек:
Enable: Yes
Node interpreter: /usr/bin/node (свой путь до интерпретатора: nodejs, node.exe)
ESLint package: /usr/lib/node_modules/eslint (свой путь до пакета eslint)
Configuration file: /home/username/project/codestyle/eslint/eslintrc.js (свой путь к файлу)
Кнопка [Apply]
После этого:
Editor → Inspections → JavaScript → Code Quality Tools → ESLint (поставить галочку)
После этого повторить эти же действия в настройках текущего проекта, если он был создан до настройки ESLint в Идее:
File → Settings
File → Settings → Languages and Frameworks → JavaScript → Libraries
Чтобы не запоминать, что где находится, можно пользоваться удобным поиском прямо в окне настроек.
Например, указанные выше плагины легко находятся с помощью поиска фраз: code sniffer, jshint, jscs.
- jscs/jscs-options.js — настройки JSCS;
- jshint/jshint-options.js — настройки JSHint;
- php-code-sniffer — каталог, содержащий в себе сам Code Sniffer и наш стиль кодирования для PHP-кода
Sijeko.
Этот каталог можно положить, например, в папку с настройками Идеи, которая находится:
- в Linux:
/home/<username>/.WebIde100 - в Windows:
C:\Users\<username>\.WebIde100 - в MacOS:
/home/<username>/.WebIde100
В случае PHP стандарт скобок равен стандартам PSR-1 и PSR-2. Для методов и классов открывающая скобка ставится на новой строке. Во всех остальных случаях (управляющие конструкции и т. д.) в конце текущей строки:
class Controller
{
/**
* Получить модель документа.
*
* @param string $alias Псевдоним документа, который нужно найти.
* @return Document Возвращает документ, заданный псевдонимом в параметре.
* @throws \app\web\HttpException
*/
protected function getModel($alias)
{
/* @var Document $model */
$model = Document::find(['alias' => $alias]);
if ($model === null) {
throw new HttpException('404', 'Not Found');
}
if (App::user->isGuest && $model->access !== Document::TYPE_PUBLIC) {
throw new HttpException('403', 'Access Denied');
}
return $model;
}
}Короткие управляющие конструкции без скобок крайне нежелательны (это чревато различными проблемами):
// Да-да-да
if (CONDITION) {
do();
}
// Нет-нет-нет
if (CONDITION)
do();С лета 2014 года короткие управляющие конструкции в коде запрещены.
Названия классов пишутся с БольшойБуквы; имена переменных, методов и прочее — со строчнойБуквы.
Приватные члены класса также пишутся со строчнойБуквы, подчёркивание в начале имени не используется.
Константы называются ЗАГЛАВНЫМИ_БУКВАМИ, слова разделяются подчёркиваниями.
Желательно для каждой константы написать PhpDoc/JsDoc.
В начале строк (indentation) отступы должны быть табуляциями. Внутри строк (alignment, выравнивание) — пробелами. Данная техника называется SmartTabs.
В PHP, JavaScript и CSS лучше использовать строки с 'одинарными кавычками', а не с "двойными".
В значениях атрибутов HTML использовать только "двойные кавычки".
Таким образом, количество проблем при смешивании кода будет сведено к минимуму.
В CSS также используются египетские скобки и жёсткая табуляция.
html, body {
padding: 0;
margin: 0;
height: 100%;
width: 100%;
}В общем случае, желательно использовать LESS вместо CSS, а вывод LESS-компилятора сразу делать минимизированным.
До марта 2014 в CSS использовался так называемый баннер-стиль отступов: закрывающая скобка выравнивалась по вложенному блоку (в данном случае это блок правил):
html, body {
padding: 0;
margin: 0;
height: 100%;
width: 100%;
}Поэтому такое расположение скобок ещё иногда может встречаться в старых проектах.
По возможности, всегда документировать классы и методы с помощью PhpDoc/JsDoc. В классах описывать члены и методы в функциях и методах описывать параметры и возвращаемые значения. Предполагается, что встроенная документация написана с использованием языка разметки Маркдаун (он не требует специальной подготовки, понятен без лишних разъяснений).
Допускается использование только Юникод-кодировки UTF-8.
Это относится, как к исходным текстам программ и кодировке базы данных,
так и к обычным текстовым файлам.
В базе данных MySQL следует использовать кодировку utf8mb4 для таблиц и полей, если она доступна
(если недоступна, выбираем по старинке utf8): она содержит более полный набор символов Юникода.
Использовать однобайтовые кодировки категорически запрещается! Те, кто используют однобайтовые кодировки (Windows/CP1251, KOI8 и прочие), попадут в ад.