WordPress codex на русском

Написание Качественных Комментариев

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

Представьте, что сделали сайт для клиента, используя ваш фреймворк. Спустя два года, в 5:30 в пятницу на сайте возникает проблема. Хорошие комментарии внесут разницу между быстрым исправлением ошибки, проведнием выходных дома и рассмотрением сотен строк кода и пропуском пятничного вечера.

Вот несколько заметок для хороших комментариев:

  • Используйте комментарии вначале вашего файла для объяснения того, что делает этот файл. Например, в файлы-шаблоны включите заметку о том, какие данные отображает этот файл и об изменениях, внесенных вами в цикл или в другую часть файла; в файлах плагина добавьте заметку о его функциональности. Например, комментарии внизу говорят пользователям название файла-шаблона, о том, что он делает, частью какой темы он является (@package), и начиная с какой версии он использовался (@since). Вы должны использовать аналогичную систему для файлов плагина.

/** * Template Name:sidebar-products.php * * The include file used for the sidebar on pages using the single-product.php template. Displays a gallery of product images (omitting the featured image which is displayed in the content). * * @package wpptl-theme-framework * @since version 1.0 */

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

Создание Файла Readme

Файл readme.txt является следующим уровнем после комментариев. Это отдельный файл, который вы включаете в вашу тему, содержащий информацию о ней.

Код, сопроваждающий эту серию, содержит в себе простой файл readme.txt:

Создание фреймворка вашей WordPress темы Эта тема поддерживает 6-ую часть этой серии для wptutsplus. Тема включает в себя следующие файлы-шаблоны: archive.php index.php page.php — for static pages page-full-width.php archive.php — for archive pages header.php sidebar.php footer.php loop.php loop-single.php loop-page.php functions.php Тема поддерживает популярные изображения, меню и виджеты и использует их следующим образом: Популярные изображения: Они отображаются в шаблонах archive и index, если они есть, используя средний размер. Меню: Меню по умолчанию находится в header.php и использует админ-панель Menus Дизайн Тема использует Объектно-ориентированный CSS (OOCSS). Следующие классы созданы для макета и вы можете использовать их в ваших страницах и постах. Они адаптивны, так что будут уменьшаться на маленьких экранах (например, класс .half будет в полную ширину на мобильных) .full-width .three-quarters .two-thirds .half .third .quarter Хуки Существует 7 хуков-действий: Над header Внутри header До контента После контента В боковой панели В footer После footer Существует 3 хука-фильтра: 1 в header 2 в footer Виджет-Зоны Существует шесть виджет-зон, все добавлены с помощью файла widgets.php: — одна в header — одна в боковой панели — четыре в footer

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

Если вы хотите выпустить ваш фреймворк через репозиторий WordPress тем, вы должны будете предоставить файл readme.txt как минимум в форме документации. Я расскажу об этом в последнем уроке этой серии, в выпуске фреймворка вашей темы.

Создание Вики-Страницы или Сайта

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

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

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

Если ваш фреймворк абсолютно бесплатный, вы можете создать бесплатный сайт с документацией, как в случае с фреймворкрм Wonderflux:

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

Создание Руководств или Видео Записей

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

Фреймворк Genesis имеет целый ряд учебных пособий для пользователей, которые доступны только платным подписчикам:

Мой собственный фреймворк Edupress имеет ряд учебных видео, которые я создала для того, чтобы помочь пользователям с различной степенью опыта работы с компьютером и небольшим опытом использования WordPress:

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

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

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

Добавить комментарий

Ваш e-mail не будет опубликован. Обязательные поля помечены *