Разработка:Стандарт кодирования — различия между версиями
Ilya (обсуждение | вклад) м (→Правила оформления кода в проекте «Электронный деканат».) |
Ilya (обсуждение | вклад) м (→Правила оформления кода в проекте «Электронный деканат».) |
||
| Строка 9: | Строка 9: | ||
== Правила оформления кода в проекте «Электронный деканат». == | == Правила оформления кода в проекте «Электронный деканат». == | ||
*Все отступы – 4 пробела. Не использовать TAB. | *Все отступы – 4 пробела. Не использовать TAB. | ||
| − | *Имена переменных - всегда легкие для чтения осмысленные слова английского языка, набранные в нижнем регистре. Несколько слов пишутся слитно. Но они должны быть как можно короче. Используйте имена во множественном числе для массивов. $courseid, $studentsgrades | + | *Имена переменных - всегда легкие для чтения осмысленные слова английского языка, набранные в нижнем регистре. Несколько слов пишутся слитно. Но они должны быть как можно короче. Используйте имена во множественном числе для массивов. Например: $courseid, $studentsgrades |
| − | *Константы всегда в верхнем регистре, всегда начинаются с имени модуля. Слова в названии разделены символом подчеркивания. SITE_ID | + | *Константы всегда в верхнем регистре, всегда начинаются с имени модуля. Слова в названии разделены символом подчеркивания. Пример: SITE_ID |
| − | *Имена глобальных переменных, состоят полностью из заглавных букв. $CFG | + | *Имена глобальных переменных, состоят полностью из заглавных букв. Пример: $CFG |
*Функции называются словами английского языка в нижнем регистре, разделенные символом подчеркивания. Начинаются с имени модуля. Затем идет часть имени, описывающая выполняемое действие. Последняя часть - это существительное, обозначающее сущность, над которой это действие производится либо набор сущностей. Не должно быть пробелов между именем функции и скобками. Это относится и к объявлению функции, и к ее использованию. Параметры всегда должны иметь разумные значения по умолчанию, если это возможно. Пример: | *Функции называются словами английского языка в нижнем регистре, разделенные символом подчеркивания. Начинаются с имени модуля. Затем идет часть имени, описывающая выполняемое действие. Последняя часть - это существительное, обозначающее сущность, над которой это действие производится либо набор сущностей. Не должно быть пробелов между именем функции и скобками. Это относится и к объявлению функции, и к ее использованию. Параметры всегда должны иметь разумные значения по умолчанию, если это возможно. Пример: | ||
modname_get_string($identifier, $pluginname = NULL) | modname_get_string($identifier, $pluginname = NULL) | ||
| Строка 43: | Строка 43: | ||
*Имя модуля может включать только строчные латинские буквы и содержать не более 20 символов. | *Имя модуля может включать только строчные латинские буквы и содержать не более 20 символов. | ||
*Имена колонок БД, содержащих ключ по другой колонке в БД Free Dean's Office должны заканчиваться на id | *Имена колонок БД, содержащих ключ по другой колонке в БД Free Dean's Office должны заканчиваться на id | ||
| − | *Имена колонок в БД, содержащих ключ объекта в собственной БД Moodle должны начинаться на | + | *Имена колонок в БД, содержащих ключ объекта в собственной БД Moodle должны начинаться на mdl_ (но не должны заканчиваться на id) |
*Следует избегать использования глобальных переменных. | *Следует избегать использования глобальных переменных. | ||
*Обращения к объектом Free Dean's Office выполняется через объект [[Разработка:lib/dof.php|$DOF]]. При объявлении плагина он должен сохранить ссылка на объект $DOF в собственном свойстве dof и во всех собственных методов использовать для обращения '''$this->dof''' | *Обращения к объектом Free Dean's Office выполняется через объект [[Разработка:lib/dof.php|$DOF]]. При объявлении плагина он должен сохранить ссылка на объект $DOF в собственном свойстве dof и во всех собственных методов использовать для обращения '''$this->dof''' | ||
Версия 16:50, 20 марта 2009
Содержание
Правила оформления кода в проекте «Электронный деканат».
- Все отступы – 4 пробела. Не использовать TAB.
- Имена переменных - всегда легкие для чтения осмысленные слова английского языка, набранные в нижнем регистре. Несколько слов пишутся слитно. Но они должны быть как можно короче. Используйте имена во множественном числе для массивов. Например: $courseid, $studentsgrades
- Константы всегда в верхнем регистре, всегда начинаются с имени модуля. Слова в названии разделены символом подчеркивания. Пример: SITE_ID
- Имена глобальных переменных, состоят полностью из заглавных букв. Пример: $CFG
- Функции называются словами английского языка в нижнем регистре, разделенные символом подчеркивания. Начинаются с имени модуля. Затем идет часть имени, описывающая выполняемое действие. Последняя часть - это существительное, обозначающее сущность, над которой это действие производится либо набор сущностей. Не должно быть пробелов между именем функции и скобками. Это относится и к объявлению функции, и к ее использованию. Параметры всегда должны иметь разумные значения по умолчанию, если это возможно. Пример:
modname_get_string($identifier, $pluginname = NULL)
- Ставьте один пробел между скобками и синтаксическими конструкциями. Это не относится к функциям и их параметрам. Пример:
if ( $a >= max($key) )
{
···· $c = $a;
}
- При использовании сторонних библиотек возможно отступление от пунктов 4, 5, 6. (см. пример). Это связано с экономией времени на переработку оформления библиотеки и сохранением стиля сопутствующего кода. Пример:
class SomeCustomClass {function classMethod(){...}}
- Блоки всегда ограничиваются фигурными скобками. При этом используется стиль Олмана:
if (<cond>)
{
····<body>
}
- Строки должны заключаться, если это возможно, одинарными кавычками.
- Двойные кавычки должны использоваться если:
- строка содержит интерпретируемые переменные;
- внутри строки должны использоваться кавычки (их можно заэкранировать слешем, но это немного снизит читаемость кода).
- Комментарии должны быть подробными и содержательными. Объяснять каждое объявление классов, функций и переменных. Каждый цикл и каждая ветвь условия должны быть пояснены содержательным смыслом выполняемых действий, например: "перебираем список товаров", "если пользователь не заполнил поле имя..."
- Комментарии к функциям и классам оформляются в формате PHPDoc
- Комментарии в строках должны быть в стиле //. Они должны быть понятными и располагаться над строкой комментируемого кода.
- Пробелы можно использовать свободно. Не надо бояться растягивать код для улучшения читабельности.
- При копировании объектов используйте PHP5-функцию копирования объектов. В MOODLE есть функция clone(), которая совместима и с PHP4 тоже.
- Если вы копируете переменную, которая может содержать объект, то используйте функцию MOODLE fullclone().
- Если функция не возвращает значений, то true обозначает успех, false - не успех. Если функция возвращает массив, в случае успешного выполнения, но отсутствия элементов в результате, функция должна возвращать пустой массив.
- Все переменные перед первым использованием необходимо инициализировать.
- Имя модуля может включать только строчные латинские буквы и содержать не более 20 символов.
- Имена колонок БД, содержащих ключ по другой колонке в БД Free Dean's Office должны заканчиваться на id
- Имена колонок в БД, содержащих ключ объекта в собственной БД Moodle должны начинаться на mdl_ (но не должны заканчиваться на id)
- Следует избегать использования глобальных переменных.
- Обращения к объектом Free Dean's Office выполняется через объект $DOF. При объявлении плагина он должен сохранить ссылка на объект $DOF в собственном свойстве dof и во всех собственных методов использовать для обращения $this->dof
- Не должно быть никакого SQL-кода за пределом справочников (плагинов storage)
- Кроме плагинов im никакие другие плагины не должны принимать запросы по http. Исключение могут составлять плагины sync, которые могут принимать входящие soap-запросы и т.п. (но и они не должны реализовывать веб-интерфейс). При этом все плагины должны быть безопасны на случай, если злоумышленик попытается обратиться по прямой ссылке к одному из их файлов (следует предотвращать запуск файла по прямой ссылке, если это может нанести урон безопасности).
- Все даты и время в базе данных хранятся в Unix Timestamp по UTC без учета летнего времени и пересчитываются в местное время при отображении.
- Если определена только дата, то время устанавливается 12:00 по полудню.
Работа со стандартными библиотеками moodle
Этот раздел будет содержать справку по работе со стандартными пакетами moodle
