 |
|
PHPClub Cookbook & FAQ => Шаблоны для наполнения? => Функция
Шаблон для функции
Этот шаблон используется, если Вы хотите разместить в PHPClub Cookbook & FAQ функцию.
Какие функции следует размещать в PHPClub Cookbook & FAQ?
В PHPClub Cookbook & FAQ приветствуются к размещению функции, которые обладают свойствами:
- функция выполняет некоторое законченное действие
- для этой функции нет аналогичной встроенной в РНР функции
- функция является расширением для некоторой встроенной в РНР функции
Какие функции не следует размещать в PHPClub Cookbook & FAQ?
- функция не была отлажена и может содержать (или – ещё хуже – содержит) в себе ошибки
- для располагаемой Вами функции есть аналог встроенной в РНР функции, которая выполняет в точности те же действия, либо имеет бо'льшую функциональность по сравнению с Вашей функцией
Что должно быть на странице с функцией?
- стандартные элементы
- строка «где я нахожусь»
- заголовок
- аннотация к функции
- содержание
- описание прототипа функции
- анализ возможности применения функции в РНР4 и в РНР5. Список требуемых библиотек.
- Всегда следует явно указывать, в каких версиях функцию можно применять
- Если в одной из версий есть встроенная аналогичная функция, то следует на это указать
- Если в какой-то из версий функцию применить нельзя, то следует указать, в каких версиях и почему.
- описание возвращаемого значения, если есть, или указание на то, что функция ничего не возвращает
- список аргументов с описанием назначения каждого аргумента
- текст функции
- текст функции должен быть качественно отформатированным, с соблюдением всех отступов
- сразу за заголовком функции следует поместить информацию об авторе функции
- имя функции должно состоять из всех маленьких букв. Слова разделяются символом подчёркивания.
- комментарии в теле функции приветствуются, но не являются обязательными
- если у функции есть несколько вариантов решения при одинаковом прототипе, то на одной странице можно привести все варианты. Варианты приводятся в разных разделах страницы. Для каждого вариант следует обязательно указать все его оличительные особенности.
- пример применения функции с подробными комментариями
- текст примера должен быть качественно отформатированным, с соблюдением всех отступов
- комментарии в примере обязательны. Желательно – к каждому оператору
- если пример можно попробовать в online, то здесь можно расположить ссылку на соответствующий скрипт
- автоматический тест (рекомендуется). Если для Вашей функции существует автоматический тест, проверяющий работоспособность функции, то его следует поместить на этой странице.
- дополнительная информация
- если функция была взята из online-источника, то ссылка на источник
- если функция обсуждается в форуме, то ссылка на соответствующие обсуждения
- если в функции использованы некоторые теоретические данные, то ссылка на страницу с их описанием
- если существуют встроенные функции РНР, которые выполняют похожие действия, или если располагаемая Вами функция является расширением одной из встроенных функци, то здесь даётся ссылка на документацию по соответствующей функции РНР
- если в PHPClub Cookbook & FAQ существуют функции, имеющие отношение к данной, то следует разместить ссылку на эти функции
Пример правильного оформления страницы с функцией
Image/Color2GrayScale
В добавляемых Вами страницах следует соблюдать все заголовки и всё оформление, как оно представлено на этой странице.
Как следует называть страницу с функцией?
Страница с функцией соответствует имени функции, из которого удалены все символы подчёркивания и первые буквы слов преобразованы в верхний регистр.
Дополнительная информация
- Пример правильного оформления страницы с функцией
Комментариев нет.
[Показать комментарии/форму]