Когда дело доходит до написания кода, независимо от используемого языка или платформы, мы, разработчики, склонны разделяться о том, сколько или мало мы должны комментировать наш код.
С одной стороны, некоторые считают, что код должен самодокументироваться. То есть это должно быть написано достаточно ясно, чтобы не нуждаться в комментариях.
С другой стороны, некоторые считают, что все должно быть прокомментировано. То есть должны быть комментарии для каждого класса, каждой функции, каждого блока и каждой строки.
Тогда, конечно, есть те, кто посередине. На самом деле, некоторые разработчики комментируют только те области своего кода, которые могут сбивать с толку, а не использовать подход «все или ничего», описанный выше.
Когда речь идет о написании кода для WordPress, у нас есть стандарты кодирования WordPress, чтобы обеспечить стандарт, по которому мы должны писать наш код; однако это не дает веских аргументов за или против комментариев кода.
В этой серии статей я собираюсь представить пример для комментариев к коду. В частности, я собираюсь рассказать о том, почему они важны, рекомендации о том, как это сделать в контексте стандартных файлов WordPress (как для тем, так и для плагинов), а также о том, как это сделать для файлов HTML, таблиц стилей и JavaScript. файлы.
Почему они имеют значение
Прежде чем рассматривать различные части, составляющие проект WordPress, я думаю, что важно обсудить, почему комментарии кода имеют значение. Конечно, большинство из нас знает, что это должно дать краткое объяснение того, что происходит с кодом, но последствия более значительны.
Несмотря на то, что у нас есть стандарты, по которым мы должны писать наш код на основе WordPress, некоторые разработчики воспринимают их как «рекомендации», не говоря уже о тех, кто о них даже не знает. Независимо от того, насколько хорошо (или насколько плохо) вы пишете свой код, это все же код .
В конце концов, если бы это было легко понять, это бы не называлось кодом (и нам не нужны были бы комментарии).
Я не верю, что мы должны писать комментарии к коду только с учетом других. Я думаю, что мы должны написать их для себя точно так же. Когда вы впервые обращаетесь к коду после того, как прошло значительное количество времени, скорее всего, вы стали лучшим программистом, освоили несколько новых методов и / или перешли от того, как вы писали код. Таким образом, может быть трудно понять, что вы пытались сделать.
И если автору кода трудно следовать, есть ли надежда для других разработчиков, которые вносят, расширяют или улучшают код?
В конечном счете, комментарии должны быть написаны как нам самим, так и другим, кто может взаимодействовать с нашим кодом. Они должны быть ясными, лаконичными и должны предоставлять любую информацию, необходимую разработчику для работы с данным разделом кода. Это включает любую информацию, которая ссылается на код в других файлах (будь то на стороне сервера или на стороне клиента).
С учетом сказанного я хотел бы рассказать о нескольких причинах и стратегиях комментирования всех файлов, которые используются при создании темы, плагина или приложения WordPress.
На стороне сервера
В зависимости от вашего проекта, файлы, которые вы должны включить, могут отличаться. Для целей этой статьи я предполагаю, что вы включаете файлы PHP, HTML-файлы, таблицы стилей и файлы JavaScript просто для того, чтобы обеспечить охват всех баз. В этой статье мы обсудим язык на стороне сервера, то есть PHP, а в следующей статье рассмотрим языки на стороне клиента.
Когда дело доходит до комментирования наших файлов PHP, есть несколько требований, которым мы должны следовать:
- Если мы пишем темы, то пользовательские шаблоны страниц требуют определенной информации заголовка , чтобы зарегистрировать их в WordPress.
- Если мы пишем плагины, то нашему плагину требуется стандартная информация о плагине .
Помимо этого, комментарии действительно требуются очень мало, поэтому очевидно, что есть возможности для улучшения.
PHPDoc
Когда дело доходит до комментирования кода в PHP, на самом деле есть предложенный способ сделать это — PHPDoc . Подобно стандартам кодирования WordPress, PHPDoc является стандартом для комментирования (или документирования) кода PHP. Он предоставляет ряд соглашений, все из которых применимы к WordPress, но подмножество, которое я вижу, используется регулярно.
Шаблоны
WordPress поддерживает два типа файлов шаблонов:
- Базовые файлы шаблонов тем, такие как индекс, одиночный, страницы, шаблоны архивов и так далее.
- Пользовательские шаблоны страниц — это файлы, которые мы разработчики создаем и которые можно применять к существующим страницам в пользовательском интерфейсе WordPress.
- Частичные шаблоны, представляющие собой фрагменты шаблонов, которые можно использовать в других шаблонах.
Когда дело доходит до документирования файлов шаблона — независимо от того, какой тип шаблона — я всегда стараюсь предоставить информацию заголовка, которая определяет имя файла, назначение файла, пакет — тему или плагин — частью которого он является, и как долго это существовало в проекте.
Например:
|
1
2
3
4
5
6
7
8
|
/**
* Template Name: Featured Projects
*
* The template used for the ‘Featured Projects’ area of the homepage.
*
* @package Project Theme
* @since 1.0
*/
|
Как видите, я предоставил требуемое Template Name для файла, но я также дал краткое описание того, что происходит внутри файла. Я также использовал директивы @package и @since чтобы @package @since .
Директива @package , по крайней мере, в контексте WordPress, представляет название темы или плагина, частью которого является данный файл.
Директива @since как долго шаблон существовал в проекте. В приведенном выше случае, очевидно, что он был в проекте с момента его первоначального выпуска, но это не редкость, когда файлы добавляются в качестве темы или зрелого плагина, в результате чего в качестве этого значения появляется другой номер версии.
Из-за природы базовых файлов шаблонов, таких как индекс, одиночный шаблон, страница, шаблоны архивов и т. Д., Нет необходимости определять « Template Name », но описание, пакет и директивы по-прежнему актуальны.
функции
Функции документирования очень похожи на шаблоны документирования. Хотя они не требуют определенного тега, такого как « Template Name », они все равно должны содержать описание назначения функции и директивы @since .
Есть также две дополнительные директивы, которые функция может включать:
-
@paramкоторый описывает тип и описание параметра, который принимает функция -
@returnкоторый описывает тип и описание того, что возвращает функция
Конечно, функции не всегда принимают параметры, а функции не всегда возвращают значения, поэтому эти две директивы необязательны.
Предполагая, что у вас есть функция, которая поддерживает обе вышеуказанные директивы, вот как вы должны ожидать появления документации:
|
1
2
3
4
5
6
7
8
|
/**
* Programmatically inserts a page into the database.
*
* @param $title The title of the page.
* @param $template_name The name of the template file located in the ‘templates’ directory.
* @return The ID of the page that was created
* @since 1.0
*/
|
Для получения дополнительной информации о каждой из этих директив вы можете просмотреть теги PHPDoc ; тем не менее, вы можете увидеть, насколько это может быть полезно для работы над темой или плагином — это избавляет от необходимости различать то, что вы или другой разработчик пытались выполнить с помощью данной функции.
Линии и блоки
Хотя существует немного рекомендаций или фактических стандартов для документирования блоков кода, я все еще считаю, что это полезно, особенно когда речь идет о более сложных циклах или условных выражениях.
Все это может быть продемонстрировано в следующем примере. Предположим, что нам нужно настроить пользовательский запрос для циклического прохождения метаданных поста, а затем удалить его, если найден определенный ключ и / или значение. Это потребует следующих шагов:
- Настройка аргументов для запроса
- Выполнение запроса
- Перебирая результаты
- Условное удаление метаданных поста
- Сброс запроса
В этом примере будут задокументированы как отдельные строки, так и условные выражения. Сначала давайте посмотрим на исходный код, а затем рассмотрим, что он делает сразу после него:
|
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
|
// Setup arguments to retrieve all published posts
$arguments = array (
‘post_type’ => ‘post’,
‘post_status’ => ‘publish’,
‘numberposts’ => -1
);
// Instantiate the query
$posts_query = new WP_Query( $arguments );
// If any posts are found, loop through them
if( $posts_query->have_posts() ) {
while( $posts_query->have_posts() ) {
$posts_query->the_post();
/*
* For each piece of post meta that is found, store its values in
* the $meta_key and $meta_value for us to check.
*/
foreach( get_post_meta( get_the_ID() ) as $meta_key => $meta_value ) {
/*
* There may be multiple meta keys (such as tweet_url_0, tweet_url_1)
* so we need to check to see if the ‘tweet_url’ is located in the
* $meta_key.
*
* If so, we can delete the post meta data
*/
if ( false != strstr( $meta_key, ‘tweet_url’ ) ) {
delete_post_meta( get_the_ID(), $meta_key );
} // end if
} // end foreach
} // end while
} // end if
// Reset the custom query so not to interfere with any other queries or The Loop
wp_reset_postdata();
|
В идеале вышеприведенные комментарии должны содержать всю документацию и пояснения, необходимые для понимания того, что происходит в коде. Возможно, единственное, что может потребоваться, — это понимание функции strstr .
Ключевой момент, который я пытаюсь сделать с помощью приведенного выше кода, заключается в том, что если мы документируем отдельные строки, то лучше придерживаться однострочного соглашения, то есть // но если мы пишем комментарий который охватывает несколько строк, всегда лучше использовать многострочный комментарий, то есть /* */ .
Обратите внимание, что не каждая строка должна быть закомментирована. Скорее, блоки (или куски) кода могут быть объяснены в многострочном комментарии, который документирует, что должно произойти, в следующем исходном коде.
Конечно, это не стандартный или предпочтительный способ сделать что-то. Это просто стратегия, которую я видел используемой, которую я ценю, и которую я использую сам.
Генерация документации
Если вы в конечном итоге будете следовать соглашениям, изложенным в PHPDoc, то есть ряд утилит, которые могут генерировать страницы документации для вашей работы. Возможно, самым популярным инструментом является phpDocumentor .
Короче говоря, phpDocumentor — это утилита, которая просматривает ваш исходный код в поисках правильно отформатированных комментариев кода PHPDoc (в частности, для классов и функций), а затем генерирует набор стилизованных страниц, собирающих информацию в ваших комментариях.
Это делает доставку ориентированной на разработчика документации с вашим приложением проще простого.
Вывод
В этой статье я рассмотрел, почему я считаю, что комментарии к коду должны быть тем, что все разработчики должны включать в свой код. Хотя Кодекс WordPress определяет базовый набор комментариев, необходимых для нашей работы и / или для взаимодействия с приложением WordPress, очевидно, что мы можем проделать еще больше работы, чтобы улучшить ясность нашего кода.
Дело в том, что мы рассмотрели только половину этого. Итак, в следующей статье мы рассмотрим документирование разметки, JavaScript и стилей.