Получите помощь, поддержку и профессиональное общение в Клубе CodeIgniter

CodeIgniter User Guide Version 2.1.0


Стиль и синтаксис

На этой странице описываются правила кодирования, применяемые при разработке вместе с CodeIgniter.

Содержание

  • Формат файлов

    Файлы должны сохраняться в кодировке UTF-8. BOM НЕ должно использоваться. В отличие от UTF-16 и UTF-32, здесь нет никакого порядка байтов, чтобы отображать в файле UTF-8, и BOM плохо повлияет на вывод PHP, не давая приложениям выводить собственные заголовки. Должны использоваться окончания строк Unix (LF).

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

    TextMate
    1. Откройте Application Preferences
    2. Нажмите Advanced, а потом выберите вкладку "Saving"
    3. В "File Encoding" укажите "UTF-8 (recommended)"
    4. В "Line Endings" укажите "LF (recommended)"
    5. Опционально: выбиерите "Use for existing files as well" если вы хотите модифицировать окончвания строк всех открываемых файлов.
    BBEdit
    1. Откройте Application Preferences
    2. Выберите слева "Text Encodings".
    3. В "Default text encoding for new documents" выберите "Unicode (UTF-8, no BOM)"
    4. Опционально: В "If file's encoding can't be guessed, use" выберите "Unicode (UTF-8, no BOM)"
    5. Выберите слева "Text Files"
    6. В "Default line breaks" выберите "Mac OS X and Unix (LF)"

    Закрывающий тег PHP

    Закрывающий тег документа PHP ?> является опциональным для PHP-парсера. Однако, если он используется, любое пустое пространство после этого тега будет производить вывод, что может вызвать ошибки PHP. По этой причине имеет смысл практически всегда пропускать закрывающий тег, и добавлять блок комментариев в конце файла. Это также помогает определить, что файл полный, а не усеченный.

    Неправильно: <?php echo "Here's my code!"; ?> Правильно: <?php echo "Here's my code!"; /* End of file myfile.php */ /* Location: ./system/modules/mymodule/myfile.php */

    Именование классов и методов

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

    Неправильно: class superclass class SuperClass Правильно: class Super_class class Super_class { function __construct() { } }

    Примеры неправильного и правильного именования:

    Неправильно: function fileproperties() // неописательно и отсутсвует разделитель - символ подчеркивания function fileProperties() // неописательно и используется ВерблюжьяНотация function getfileproperties() // лучше! Но все еще нет разделителя, символа подчеркивания function getFileProperties() // используется ВерблюжьяНотация function get_the_file_properties_from_the_file() // многословно Правильно: function get_file_properties() // описательно, с символом подчеркивания, все в нижнем регистре

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

    Правила именования переменных соответствуют правилам для классов. А именно: переменные должны содержать только строчные буквы, использовать символы подчеркивания, и называться осмысленно в соответствии с их целями и назначением. Очень короткие переменные могут использоваться только в качестве итераторов для цикла for().

    Неправильно: $j = 'foo'; // единственная буква имени переменной, которая может использоваться только для циклов for() $Str // содержит символы в верхнем регистре $bufferedText // использует ВерблюжьюНотацию, и может быть сокращена без потери семантического значения $groupid // много слов, не разделенных символом подчеркивания $name_of_last_city_used // слишком длинное Правильно: for ($j = 0; $j < 10; $j++) $str $buffer $group_id $last_city

    Комментарии

    Вообще, код должен быть плодотворно комментирован. Это не только поможет разобраться в вашем коде другим разработчикам, но и может вам, когда вы вернетесь к этому коду спустя несколько месяцев. Здесь нет единого требуемого формата комментариев, но рекомендуется следующее.

    Стиль комментариев DocBlock, для классов и методов, который будут подхватывать IDE:

    /** * Super Class * * @package Package Name * @subpackage Subpackage * @category Category * @author Author Name * @link http://example.com */ class Super_class { /** * Encodes string for use in XML * * @access public * @param string * @return string */ function xml_encode($str)

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

    // отбивка пустой строкой $parts = explode("\n", $str); // A longer comment that needs to give greater detail on what is // occurring and why can use multiple single-line comments. Try to // keep the width reasonable, around 70 characters is the easiest to // read. Don't hesitate to link to permanent external resources // that may provide greater detail: // // http://example.com/information_about_something/in_particular/ $parts = $this->foo($parts);

    Константы

    Именование констант аналогично правилам именования переменных, за исключением того, что имена констант всегда пишутся большими буквами. Всегда используйте константы CodeIgniter, когда это возможно, т.е. SLASH, LD, RD, PATH_CACHE, и другие.

    Неправильно: myConstant // пропущен знак подчеркивания и не полностью большими буквами N // нет констант из одной буквы S_C_VER // неописательно $str = str_replace('{foo}', 'bar', $str); // необходимо использовать константы LD и RD Правильно: MY_CONSTANT NEWLINE SUPER_CLASS_VERSION $str = str_replace(LD.'foo'.RD, 'bar', $str);

    TRUE, FALSE и NULL

    Ключевые слова TRUE, FALSE и NULL должны всегда писаться большими буквами.

    Неправильно: if ($foo == true) $bar = false; function foo($bar = null) Правильно: if ($foo == TRUE) $bar = FALSE; function foo($bar = NULL)

    Логические операторы

    Использование || не рекомендуется, так как на некоторых слишком маленьких экранах устройств читается плохо (например, похоже на цифру 11). && предпочтительнее, чем AND, но также применимо, и всегда до и после должны присутствовать пробелы!

    Неправильно: if ($foo || $bar) if ($foo AND $bar) // нормально, но не рекомендуется для общих режимов подсветки синтаксиса if (!$foo) if (! is_array($foo)) Правильно: if ($foo OR $bar) if ($foo && $bar) // рекомендуется if ( ! $foo) if ( ! is_array($foo))

    Сравнение возвращаемых значений и приведение типов

    Некоторые функции PHP возвращают FALSE при неудаче, но также могут возвращать правильные значения "" или 0, которые могут вызвать некорректные результаты при мягком сравнении. Использование жесткого сравнения позволит быть уверенным, что возвращенное значение точно соответствует ожидаемому. Используйте === и !== при необходимости. Неправильно: // Если 'foo' присутствует в начале строки, функция strpos вернет 0, // и тогда результатом сравнения будет TRUE if (strpos($str, 'foo') == FALSE) Правильно: if (strpos($str, 'foo') === FALSE) Неправильно: function build_string($str = "") { if ($str == "") // ой-ой, что будет, если в аргументе будет передано FALSE или 0 { } } Правильно: function build_string($str = "") { if ($str === "") { } }

    Смотрите также информацию насчет приведения типов, которая может быть чрезвычайно полезной. Приведение типов может иметь другой эффект, который не соответствует ожидаемому. Например, когда сравниваются переменная, как строка, с NULL, или булево FALSE c пустой строгой, ноль (и другие числа) приводится к виду строки, и сравнение будет возвращать TRUE, что приведет к некорректной работе вашей программы:

    $str = (string) $str; // cast $str as a string

    Отладка кода

    Нельзя оставлять незакомментированный отладочный код. в том числе вызовы var_dump(), print_r(), die(), and exit(), которые были использованы при создании дополнений.

    // print_r($foo);

    Пустые места в файлах

    Не должно быть пустого места перед открывающим тегом PHP, и следом за закрывающим тегом. Вывод буферизуется, поэтому пустое место в ваших файлах может создавать проблемы, делая вывод до того, как CodeIgntier начнет выводить ваш контент. Появится любимая ошибка "Headers are always sended by". В примере ниже, выделите текст мышкой, чтобы увидеть некорректное пустое место над тегом.

    Неправильно:

    <?php // ...there is whitespace and a linebreak above the opening PHP tag // as well as whitespace after the closing PHP tag ?>

    Правильно:

    <?php // this sample has no whitespace before or after the opening and closing PHP tags ?>

    Совместимость

    Весь код должен быть совместим с PHP версии 5.1 и выше. Кроме того, не стоит использовать функции PHP, которые требуют установки устаревших библиотек.

    Имена классов и функций, использующие общие слова

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

    Неправильно: class Email pi.email.php class Xml ext.xml.php class Import mod.import.php Правильно: class Pre_email pi.pre_email.php class Pre_xml ext.pre_xml.php class Pre_import mod.pre_import.php

    Имена таблиц базы данных

    Любые таблицы, которые использует ваше дополнение, должны иметь префикс exp_, следующий за уникальным префиксом, идентифицирующим ваше вас как разработчика или компанию, и затем короткое описательное имя таблицы. Вам не нужно беспокоиться о префиксе, который будет использован при инсталляции, так как класс БД CodeIgniter автоматически конвертирует exp_ в то, что актуально используется.

    Неправильно: email_addresses // пропущены оба префикса pre_email_addresses // пропущен префикс exp_ exp_email_addresses // пропущен уникальный префикс Правильно: exp_pre_email_addresses

    Примечание: Помните, что MySQL имеет ограничение в 64 символа для имен таблиц. Это не долджно быть проблемой, потому как имена таблиц, которые явно превышают это ограничение, очевидно являются необоснованно длинными. Например, следующее имя таблицы превышает это ограничение на один символ. Глупо, не так ли? exp_pre_email_addresses_of_registered_users_in_seattle_washington

    Один файл на класс

    Используйте раздельные имена файлов для каждого класса, за исключением очень близких классов. Примером в CodeIgniter будут файлы, которые содержат множество классов в файле класса Database. Он содержит класс DB и класс DB_cache, и плагин Magpie, который содержит классы Magpie и Snoopy.

    Пробелы

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

    Переносы строк

    Файлы должны сохраняться с окончаниями строк в стиле Unix. Это скорее вопрос для разработчиков, работающих с Windows, но в любом случае убедитесь, что ваш текстовый редактор настроен на сохранение файлов с LF на концах строк.

    Идентификация кода

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

    Неправильно: function foo($bar) { // ... } foreach ($arr as $key => $val) { // ... } if ($foo == $bar) { // ... } else { // ... } for ($i = 0; $i < 10; $i++) { for ($j = 0; $j < 10; $j++) { // ... } } Правильно: function foo($bar) { // ... } foreach ($arr as $key => $val) { // ... } if ($foo == $bar) { // ... } else { // ... } for ($i = 0; $i < 10; $i++) { for ($j = 0; $j < 10; $j++) { // ... } }

    Скобки

    Скобки не должны иметь дополнительные пробелы. За исключением случаев, когда управляющие структуры PHP принимают аргументы в скобках (declare, do-while, elseif, for, foreach, if, switch, while), чтобы отличать их от функций и более удобно читать код.

    Неправильно: $arr[ $foo ] = 'foo'; Правильно: $arr[$foo] = 'foo'; // нет пробелов у ключа Неправильно: function foo ( $bar ) { } Правильно: function foo($bar) // нет пробелов в скобках при декларации функции { } Неправильно: foreach( $query->result() as $row ) Правильно: foreach ($query->result() as $row) // один пробел перед управляющей структурой PHP, но не внутри скобок

    Локализованый текст

    Любой текст, который вы отправляете в вывод панели управления, должен использовать языковые переменные, установленные в вашем языковом файле.

    Неправильно: return "Invalid Selection"; Правильно: return $this->lang->line('invalid_selection');

    Приватные методы и переменные

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

    convert_text() // публичный метод _convert_text() // приватный метод

    Ошибки PHP

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

    Убедитесь что вывод ошибок всех типов включен во время разработки. Вы можете проверить эту установку следующим образом:

    if (ini_get('display_errors') == 1) { exit "Enabled"; }

    На некоторых серверах display_errors выключено, и вы не можете изменить это в php.ini, но можете включить вывод ошибок так:

    ini_set('display_errors', 1);

    Примечание: Установка display_errors вместе с ini_set() в реальном времени не идентична включению этих опций в окружении PHP. А именно, это не будет иметь никакого эффекта при критических ошибках.

    Короткие открывающие теги

    Всегда используйте полные открывающие теги, так как на некоторых серверах short_open_tag может быть выключено.

    Неправильно: <? echo $foo; ?> <?=$foo?> Правильно: <?php echo $foo; ?>

    Одно заявление на строке

    Никогда не объединяйте заявления на одной строке.

    Неправильно: $foo = 'this'; $bar = 'that'; $bat = str_replace($foo, $bar, $bag); Правильно: $foo = 'this'; $bar = 'that'; $bat = str_replace($foo, $bar, $bag);

    Строки

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

    Неправильно: "My String" // нет парсинга, поэтому не стоит использовать двойные кавычки "My string $foo" // нужны скобки 'SELECT foo FROM bar WHERE baz = \'bag\'' // уродливо Правильно: 'My String' "My string {$foo}" "SELECT foo FROM bar WHERE baz = 'bag'"

    Запросы SQL

    Ключевые слова MySQL всегда пишутся большими буквами: SELECT, INSERT, UPDATE, WHERE, AS, JOIN, ON, IN, etc.

    Разбивайте длинные запросы по смыслу на несколько строк.

    Неправильно: // ключевые слова в нижнем регистре и запрос слишком длинный // для одной строки $query = $this->db->query("select foo, bar, baz, foofoo, foobar as raboof, foobaz from exp_pre_email_addresses ...where foo != 'oof' and baz != 'zab' order by foobaz limit 5, 100"); Правильно: $query = $this->db->query("SELECT foo, bar, baz, foofoo, foobar AS raboof, foobaz FROM exp_pre_email_addresses WHERE foo != 'oof' AND baz != 'zab' ORDER BY foobaz LIMIT 5, 100");

    Аргументы функций по умолчанию

    Каждый раз предоставляйте функциям значения аргументов по умолчанию. Это поможет предотвратить ошибки PHP и несколько уменьшить количество кода. Пример:

    function foo($bar = '', $baz = FALSE)
  • Поделиться


    Переведено в компании Аринт.

    Спасибо!

    Вы тоже можете оказать помощь проекту! Как это сделать?

    Помощь и поддержка

    Вы можете задать вопросы и получить ответы и советы от гуру CodeIgniter и веб-разработки: вступайте в Клуб CodeIgniter

    Яндекс.Метрика