Разработка:Стандарт кодирования — различия между версиями

Материал из DOF
Перейти к: навигация, поиск
(→‎Работа с XMLDB)
(→‎Правила оформления кода в проекте «Электронный деканат».)
Строка 8: Строка 8:
  
 
== Правила оформления кода в проекте «Электронный деканат». ==
 
== Правила оформления кода в проекте «Электронный деканат». ==
−
Все отступы – 4 пробела. Не использовать TAB.
+
*Все отступы – 4 пробела. Не использовать TAB.
−
----
+
*Имена переменных - всегда легкие для чтения осмысленные слова английского языка, набранные в нижнем регистре. Несколько слов пишутся слитно. Но они должны быть как можно короче. Используйте имена во множественном числе для массивов. $courseid, $studentsgrades
−
Имена переменных - всегда легкие для чтения осмысленные слова английского языка, набранные в нижнем регистре. Несколько слов пишутся слитно. Но они должны быть как можно короче. Используйте имена во множественном числе для массивов. $courseid, $studentsgrades
+
*Константы всегда в верхнем регистре, всегда начинаются с имени модуля. Слова в названии разделены символом подчеркивания. SITE_ID
−
----
+
*Имена глобальных переменных, состоят полностью из заглавных букв. $CFG
−
Константы всегда в верхнем регистре, всегда начинаются с имени модуля. Слова в названии разделены символом подчеркивания. SITE_ID
+
*Функции называются словами английского языка в нижнем регистре, разделенные символом подчеркивания. Начинаются с имени модуля. Затем идет часть имени, описывающая выполняемое действие. Последняя часть - это существительное, обозначающее сущность, над которой это действие производится либо набор сущностей. Не должно быть пробелов между именем функции и скобками. Это относится и к объявлению функции, и к ее использованию. Параметры всегда должны иметь разумные значения по умолчанию, если это возможно. Пример:
−
----
+
    modname_get_string($identifier, $pluginname = NULL)
−
Имена глобальных переменных, состоят полностью из заглавных букв. $CFG
+
*Ставьте один пробел между скобками и синтаксическими конструкциями. Это не относится к функциям и их параметрам. Пример:
−
----
+
    if ( $a >= max($key) )
−
Функции называются словами английского языка в нижнем регистре, разделенные символом подчеркивания. Начинаются с имени модуля. Затем идет часть имени, описывающая выполняемое действие. Последняя часть - это существительное, обозначающее сущность, над которой это действие производится либо набор сущностей. Не должно быть пробелов между именем функции и скобками. Это относится и к объявлению функции, и к ее использованию. Параметры всегда должны иметь разумные значения по умолчанию, если это возможно.
+
    {
 +
   
 +
    ···· $c = $a;
 +
   
 +
    }
  
−
modname_get_string($identifier, $pluginname = NULL)
+
*При использовании сторонних библиотек возможно отступление от пунктов 4, 5, 6. (см. пример). Это связано с экономией времени на переработку оформления библиотеки и сохранением стиля сопутствующего кода. Пример:
−
----
+
    class SomeCustomClass {function classMethod(){...}}
−
Ставьте один пробел между скобками и синтаксическими конструкциями. Это не относится к функциям и их параметрам.
+
*Блоки всегда ограничиваются фигурными скобками. При этом используется стиль Олмана:
−
 
+
    if (<cond>)
−
if ( $a >= max($key) )
+
    {
−
 
+
    ····<body>
−
{
+
    }
−
 
+
*Строки должны заключаться, если это возможно, одинарными кавычками.
−
···· $c = $a;
+
*Двойные кавычки должны использоваться если:
−
 
+
**строка содержит интерпретируемые переменные;
−
}
+
**внутри строки должны использоваться кавычки (их можно заэкранировать слешем, но это немного снизит читаемость кода).
−
----
+
*Комментарии должны быть подробными и содержательными. Объяснять каждое объявление классов, функций и переменных. Каждый цикл и каждая ветвь условия должны быть пояснены содержательным смыслом выполняемых действий, например: "перебираем список товаров", "если пользователь не заполнил поле имя..."
−
При использовании сторонних библиотек возможно отступление от пунктов 4, 5, 6. (например class SomeCustomClass {function classMethod(){...}}). Это связано с экономией времени на переработку оформления библиотеки и сохранением стиля сопутствующего кода.
+
*Комментарии к функциям и классам оформляются в формате PHPDocs
−
----
+
*Комментарии в строках должны быть в стиле '''//'''. Они должны быть понятными и располагаться над строкой комментируемого кода.
−
Блоки всегда ограничиваются фигурными скобками. При этом используется стиль Олмана:
+
*Пробелы можно использовать свободно. Не надо бояться растягивать код для улучшения читабельности.
−
 
+
*При копировании объектов используйте PHP5-функцию копирования объектов. В MOODLE есть функция clone(), которая совместима и с PHP4 тоже.
−
if (<cond>)
+
*Если вы копируете переменную, которая может содержать объект, то используйте функцию MOODLE fullclone().
−
 
+
*Если функция не возвращает значений, то true обозначает успех, false - не успех. Если функция возвращает массив, в случае успешного выполнения, но отсутствия элементов в результате, функция должна возвращать пустой массив.
−
{
+
*Все переменные перед первым использованием необходимо инициализировать.
−
····<body>
+
*Имя модуля может включать только строчные латинские буквы и содержать не более 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 без учета летнего времени и пересчитываются в местное время при отображении.
−
# внутри строки должны использоваться кавычки (их можно заэкранировать слешем, но это немного снизит читаемость кода).
 
−
----
 
−
Комментарии должны быть подробными и содержательными. Объяснять каждое объявление классов, функций и переменных. Каждый цикл и каждая ветвь условия должны быть пояснены содержательным смыслом выполняемых действий, например: "перебираем список товаров", "если пользователь не заполнил поле имя..."
 
−
----
 
−
Комментарии к функциям и классам оформляются в формате PHPDocs
 
−
----
 
−
Комментарии в строках должны быть в стиле //.
 
−
 
 
−
Они должны быть понятными и располагаться над строкой комментируемого кода.
 
−
----
 
−
Пробелы можно использовать свободно. Не надо бояться растягивать код для улучшения читабельности.
 
−
----
 
−
При копировании объектов используйте 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 по полудню.
 
Если определена только дата, то время устанавливается 12:00 по полудню.
  

Версия 16:06, 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>
   }
  • Строки должны заключаться, если это возможно, одинарными кавычками.
  • Двойные кавычки должны использоваться если:
    • строка содержит интерпретируемые переменные;
    • внутри строки должны использоваться кавычки (их можно заэкранировать слешем, но это немного снизит читаемость кода).
  • Комментарии должны быть подробными и содержательными. Объяснять каждое объявление классов, функций и переменных. Каждый цикл и каждая ветвь условия должны быть пояснены содержательным смыслом выполняемых действий, например: "перебираем список товаров", "если пользователь не заполнил поле имя..."
  • Комментарии к функциям и классам оформляются в формате PHPDocs
  • Комментарии в строках должны быть в стиле //. Они должны быть понятными и располагаться над строкой комментируемого кода.
  • Пробелы можно использовать свободно. Не надо бояться растягивать код для улучшения читабельности.
  • При копировании объектов используйте 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

Работа с moodleQuickForm

Работа с moodleExcelWorkbook

Работа с XMLDB

Источник — «http://docs.deansoffice.ru/wiki/index.php?title=Разработка:Стандарт_кодирования&oldid=455»