Хороший стиль кодинга (программирования) на php. Часть 2 Названия.

Используйте подходящие имена

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

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

Если вы обнаружите, что Вы обнаружите, что все Ваши имена похожи на temp, $d, $temp2, то, возможно, Вам стоит серьезно пересмотреть взгляды.

Названия классов

• Давайте название классу только после того, как становится полностью очевидно, какими функциями он будет оперировать. Если Вы не можете полностью осмыслить, что предстоит делать функции или классу, то соответственно и название полностью соответствующее разработать не сможете.
• Составляя названия более чем из 3 слов, Вы рискуете запутаться и отойти от начального проекта. Пересмотрите концепт.
• Старайтесь избегать искушения называть классы в виде производной названия родительского класса. Каждый класс несет в себе отдельную функцию и должен иметь собственное, самостоятельно название.
• Суффиксы зачастую полезны. Например, если Ваша система использует агентов, то  название будет DownloadAgent соответствовать действительности.
• Используйте только английские названия. Старайтесь не использовать кириллистических названий и транскрипций

Названия методов и функций

• Обычно каждый метод и функция выполняют свое действие, таким образом, название должно четко объяснять, что делает этот класс или функция: CheckForErrors() вместо ErrorCheck(), DumpDataToFile() вместо DataFile(). Это также делает функции и объекты более distinguishable.
• Суфиксы часто полезны:
• • Max - означает максимально возможное значение.
  • Cnt – текущий счетчик изменяющего значения переменной.
  • Key – ключ.

Например: RetryMax означает максимальное количество повторов, RetryCnt означает текущий счетчик повторов.

• Префиксы также часто полезны:
• • Is – используйте чтобы задать вопрос. Когда кто-то видит Is, он понимает, что речь идет о вопросе, так как в английском языке вопросы чаще всего начинаются в Is.
  • Get – Получить значение.
  • Set – Установить значение.

Для примера: IsHitRetryLimit.

Не используйте все прописные (большие) буквы в аббревиатурах.

• Старайтесь не использовать написание “все прописные буквы” в названиях, даже когда речь идет об очень распространенной аббревиатуре. В любой ситуации.
  
  Используйте: GetHtmlStatistic.
  Не используйте: GetHTMLStatistic.

Мотивация

• Люди увидев название могут последовать самой не предсказуемой логике. Лучше использовать вариант, в котором двусмысленность невозможна.
• Например NetworkABCKey. Обратите как двояка буква С от слова ABC и K от слова Key. Кто-то вообще не обратит внимание, но все равно рано или поздно попадется тот, кто поймет текст не правильно..

Пример

   class FluidOz             // а не FluidOZ
   class GetHtmlStatistic    // а не GetHTMLStatistic

• Используйте верхний регистра для разделения слов, и нижний для всех символов кроме первого.
• Первый символ в названии должен быть с большой буквы
• Не используйте подчеркивание('_')

Мотивация

• Изо всех возможных вариантов множество людей согласились с тем, что это лучший вариант.

Пример

   class NameOneTwo
   class Name

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

Пример

John Johnson написал библиотеку и использует JJ в качестве префикса для классов:

   class JjLinkList
   {
   }

• Используйте те же методы, что и в названиях классов.

Мотивация

• Изо всех возможных вариантов множество людей согласились с тем, что это лучший вариант.

Пример

   class NameOneTwo
   {
      function DoIt() {};
      function HandleError() {};
   }

• Аттрибуты (переменные) классов должны иметь префикс “m”
• После “m” следует применять обычные правила для названий классов
• “m” всегда стоит впереди всех дополнительных модификаторов

Мотивация

• Использование 'm' позволяется избежать конфликтов с именами других элементов класса.   Часто названия классов и аттрибутов очень похожи, особенно не для автора.

Пример

   class NameOneTwo
   {
      function VarAbc() {};
      function ErrorNumber() {};
      var $mVarAbc;
      var $mErrorNumber;
      var $mrName;
   }

• Первый символ должен быть в нижнем регистре.
• Все слова начинающиеся после первого слова должны начинаться с большой буквы

Мотивация

• Вы всегда сможете сказать какие переменные передаются как параметры.

Пример

   class NameOneTwo
   {
      function StartYourEngines(&$someEngine, &$anotherEngine) {
        $this->mSomeEngine = $someEngine;
        $this->mAnotherEngine = $anotherEngine;
      }

     var $mSomeEngine;
      var $mAnotherEngine;
   }

• Используйте все буквы в нижнем регистре
• используйте подчеркивание '_' для разделения слов.

Мотивация

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

Пример

function HandleError($errorNumber)
{
    $error = new OsError;
    $time_of_error = $error->GetTimeOfError();
    $error_processor = $error->GetErrorProcessor();
}

• Ссылки следует предварять префиксом 'r'.

Мотивация

• Различие между переменными будет кристально понятным.
• Это устанавливает различие между методом, возвращающим поддающийся изменению объекты и то же самым названием метода, возвращающим неподдающийся изменению объект.  

Пример

class Test
{
    var $mrStatus;
    function DoSomething(&$rStatus) {};
    function &rStatus() {};
}

• Все глобальные переменные следует префиксировать 'g'.

Мотивация

• Очень важно, чтобы было сразу видно зону действия переменной.

Пример

    global $gLog;
    global &$grLog;

• Глобальные переменные должны быть названы используя все символы в верхнем регистре и с разделителем в виде подчеркивания “_” между словами.

Мотивация

Уже стало традицией называть константы именно таким образом. Вы не спутаете тогда значение с другими глобальными значениями.

Пример

define("A_GLOBAL_CONSTANT", "Hello world!");

• Вы можете предварять статические переменные символом 's'.

Мотивация

• Это важно знать область в которой используется переменная.

Пример

function test()
{
  static $msStatus = 0;
}

• Для функций PHP следует использовать тебе же правила, что описано в GNU соглашении для C. Используйте все буквы в нижнем регистре с подчеркиванием '_' в качестве разделителя слов.

Мотивация

• Это делает функции в корне отличными от классов.

Пример

function some_bloody_function()
{
}