Welcome to php club

PHP FAQ from PHPclub.ru: CookbookTemplateFunction ...

Начало | Каталог | Изменения | НовыеКомментарии | Вам запрещён доступПользователи | Вам запрещён доступРегистрация | Вход:  Пароль:  

PHPClub Cookbook & FAQ => Шаблоны для наполнения? => Функция

Шаблон для функции


Этот шаблон используется, если Вы хотите разместить в PHPClub Cookbook & FAQ функцию.


Оглавление документа

Какие функции следует размещать в PHPClub Cookbook & FAQ?


В PHPClub Cookbook & FAQ приветствуются к размещению функции, которые обладают свойствами:


  • функция выполняет некоторое законченное действие

  • для этой функции нет аналогичной встроенной в РНР функции

  • функция является расширением для некоторой встроенной в РНР функции

Какие функции не следует размещать в PHPClub Cookbook & FAQ?


  • функция не была отлажена и может содержать (или – ещё хуже – содержит) в себе ошибки

  • для располагаемой Вами функции есть аналог встроенной в РНР функции, которая выполняет в точности те же действия, либо имеет бо'льшую функциональность по сравнению с Вашей функцией

Что должно быть на странице с функцией?


  • стандартные элементы
    • строка «где я нахожусь»
    • заголовок
    • аннотация к функции
    • содержание

  • описание прототипа функции

  • анализ возможности применения функции в РНР4 и в РНР5. Список требуемых библиотек.
    • Всегда следует явно указывать, в каких версиях функцию можно применять
    • Если в одной из версий есть встроенная аналогичная функция, то следует на это указать
    • Если в какой-то из версий функцию применить нельзя, то следует указать, в каких версиях и почему.

  • описание возвращаемого значения, если есть, или указание на то, что функция ничего не возвращает

  • список аргументов с описанием назначения каждого аргумента

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

  • пример применения функции с подробными комментариями
    • текст примера должен быть качественно отформатированным, с соблюдением всех отступов
    • комментарии в примере обязательны. Желательно – к каждому оператору
    • если пример можно попробовать в online, то здесь можно расположить ссылку на соответствующий скрипт

  • автоматический тест (рекомендуется). Если для Вашей функции существует автоматический тест, проверяющий работоспособность функции, то его следует поместить на этой странице.

  • дополнительная информация
    • если функция была взята из online-источника, то ссылка на источник
    • если функция обсуждается в форуме, то ссылка на соответствующие обсуждения
    • если в функции использованы некоторые теоретические данные, то ссылка на страницу с их описанием
    • если существуют встроенные функции РНР, которые выполняют похожие действия, или если располагаемая Вами функция является расширением одной из встроенных функци, то здесь даётся ссылка на документацию по соответствующей функции РНР 
    • если в PHPClub Cookbook & FAQ существуют функции, имеющие отношение к данной, то следует разместить ссылку на эти функции

Пример правильного оформления страницы с функцией
Image/Color2GrayScale
В добавляемых Вами страницах следует соблюдать все заголовки и всё оформление, как оно представлено на этой странице.

Как следует называть страницу с функцией?


Страница с функцией соответствует имени функции, из которого удалены все символы подчёркивания и первые буквы слов преобразованы в верхний регистр.

Дополнительная информация


  • Пример правильного оформления страницы с функцией

 
Комментариев нет. [Показать комментарии/форму]