Соглашения по написанию кода для веб-разработки

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

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

Другими словами, соглашения по написанию кода – это набор руководств и правил для определенного языка программирования, которые рекомендуют определенный стиль программирования, методы и устоявшиеся практики по написанию любых сценариев на данном языке.

Эти соглашения обычно покрывают такие стороны программирования, как комментарии, организация папок и файлов, отступы, объявления, пробелы, правила именования, практика и принципы программирования, примеры лучших архитектурных практик и т.п.

Мы советуем вам следовать этим правилам при написании кода. Это поможет улучшить читаемость вашего кода, и тем самым, сделает его поддержку легче.

Большинство наших примеров даны на PHP, но все правила легко применимы ко всем другим языкам для веб-программирования.

1.Табуляция

Вначале я бы порекомендовал вам определиться с вопросом: что использовать – tab или пробелы? Вообще, отступы не являются необходимым условием для большинства языков программирования, где они используются в качестве вторичного обозначения.

Разработчики делают отступы для того, чтобы лучше передать структуру своих программ читателям. В частности, отступы используются, чтобы показать связь между конструкциями управления исполнением (такими как условия или циклы) и кодом, заключенным внутри и вне этих конструкций.

Я никогда не понимал споров относительно табуляции и пробелов. Но как бы то ни было, я могу порекомендовать вам использовать четыре пробела вместо символа табуляции.

У меня есть полезный аргумент на этот счет: когда мы просматриваем и сравниваем коды, используя разное программное обеспечение (скажем, мы сравниваем два файла в Total Commander), символы табуляции и пробелы выглядят по-разному.

Просто попробуйте сделать отступ в двух строках, в первой с помощью tab и во второй – с помощью четырех пробелов. В Notepad++ это будет выглядеть одинаково. Но попробуйте сравнить файл с его резервной копией (в Total Commander) и вы обнаружите, что символ табуляции выглядит длиннее, чем четыре пробела (как результат вы можете получить плохо отформатированный код).

Поэтому, пожалуйста, настройте вашу программу так, чтобы использовать четыре пробела вместо символа табуляции, когда вы нажимаете кнопку «Tab». Это пригодится вам в будущем.

2. Имена классов

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

Пример:

class MyClassName {
    function MyClassName() {	
    }
}

3. Имена переменных

Так как строгая типизация данных (в большинстве веб-языков) отсутствует (хотя и является доступной), для удобства имя переменной должно начинаться со строчной буквы первого символа из названия конкретного типа данных.

Возможные приставки к типам:

i: integer
f: float / double
s: string
a: array
o: object
r: resource
b: boolean
is: boolean

После префикса вы можете использовать «верблюжий» стиль (каждое слово, использованное в имени переменной, должно начинаться с заглавной буквы). Если вам нужно объявить переменную типа private, вы можете воспользоваться нижним подчеркиванием.

Примеры (на PHP):

public $sFirstName = "some value";
public $sSecondName = "some value";
private $_iVariable;  
$iDigit1 = $iDigit2 = 10;
$oMyClass = new MyClass();

4. Имена констант

Константы это статические переменные, и это значит, что их значения не изменяются. Обычно для констант используются все заглавные буквы (не забывайте о возможных префиксах).

Пример:

define('PRJ_WEBSITE_URL', 'http://www.website.com/');
define('PRJ_GLOBAL_CURRENCY', '$');

5. Объявление функций (имена и форматирование)

Имена всех функций должны начинаться со строчной буквы, а каждое слово – с заглавной буквы. Фигурные скобки должны стоять на той же строке (после списка параметров).

Пример:

function getPropertyValue($sName) {
    // здесь пользовательский код
}
function setPropertyValue($sName, $sValue) {
    // здесь пользовательский код
}

6. Форматирование особенных структур

Особенные структуры, например, if/else, for, foreach, while и т.д., должны следовать следующим правилам:

  • Должен быть пробел между именем структуры и следующей за ним скобкой (для более удобного чтения);
  • Условия, заключенные в скобки, должны быть разделены пробелом (по той же причине);
  • Не должно быть пробелов после левой скобки и перед правой;
  • Открытая фигурная скобка должна быть на той же строке;
  • Внутренние условия (операторы case или другой код) должны быть выделены отступом при помощи табуляции.

Примеры:

foreach ($aKeys as $iKey => $sValue) {
    // здесь пользовательский код
}
if ($bCondition) {
    // здесь пользовательский код
} else {
    // здесь пользовательский код
}
switch ($sKey) {
    case 1:
        // здесь пользовательский код
        break;
    case 2:
        // здесь пользовательский код
        break;
    default:
        // здесь пользовательский код
        break;
}

7. Названия таблиц базы данных

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

Например:

CREATE TABLE IF NOT EXISTS `myprj_records_table` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `pid` int(11) NOT NULL,
  `snippet` varchar(128) NOT NULL,
  `description` varchar(255) NOT NULL,
  UNIQUE KEY `id` (`id`)
) ENGINE=MyISAM  DEFAULT CHARSET=utf8;

8. Структура каталога проекта

Когда мы работаем в команде, очень важно соблюдать структуру папок и файлов в логическом порядке. Не помещайте все в одну папку без какой-либо организации, иначе это превратится в свалку.

Пример:

/root  folder
  /backup
  /cache
  /classes
  /css
  /js
  /media
    /images
    /mp3
    /video
  index.php
  otherFiles.php

Заключение

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

Я надеюсь, вам понравилась наша статья. Было бы здорово, если бы вы поделились ею с вашими друзьями. Удачи и ждем вас назад!

Перевод статьи «Coding conventions in web development» был подготовлен дружной командой проекта Сайтостроение от А до Я.

20 декабря 2013 в 12:10
Материалы по теме
{"url":"http://www.fastvps.ru/", "src":"/images/advbanners/fastvps.png", "alt":"Хостинг Fastvps.ru. Наш выбор!"}
Заработок