В этой серии из двух частей мы рассмотрим создание кейса для комментариев кода. В первой статье мы рассмотрели серверную часть, взглянув на PHP. В частности, мы рассмотрели соглашения PHPDoc и их использование для документирования шаблонов, функций, а также строк и блоков.
В этой статье мы рассмотрим языки на стороне клиента. В частности, мы рассмотрим HTML, CSS и JavaScript.
Хотя не обязательно есть утилиты для документирования, такие как phpDocumentor для всех этих языков, все же есть стратегии, которые мы можем использовать, чтобы сделать обслуживание наших проектов (или помочь другим внести свой вклад в наши проекты) немного проще.
Языки на стороне клиента
Когда дело доходит до работы с WordPress, темы и плагины будут различаться по типу файлов, которые они включают. Темы обычно состоят из HTML и CSS и, возможно, некоторого JavaScript, тогда как плагины могут состоять только из PHP.
В первой статье мы рассмотрели, что требуется WordPress для регистрации файлов шаблонов в API, а также какие плагины требуются. Прежде чем читать дальше, я рекомендую сначала прочитать эту статью, так как она охватывает необходимую информацию, тогда как эта конкретная статья будет содержать только рекомендации относительно того, что мы можем сделать, чтобы улучшить наши комментарии.
наценка
Большинство веб-разработчиков знают, как писать комментарии в контексте HTML. Проще говоря, это вопрос префикса кода — будь то одна строка или блок — с помощью <!-- и суффикс кода с --> . Когда дело доходит до написания разметки, не очень часто можно увидеть комментарии, помимо условных, которые вы можете найти в элементе head документа.
Существуют методы, которые мы можем использовать, чтобы сделать наш код более понятным. Это особенно полезно при работе с системами, такими как WordPress, поскольку некоторые элементы будут распределены по нескольким файлам.
Например, предполагая, что вы создаете тему, вы, вероятно, собираетесь открыть свой элемент body элемент контейнера в шаблоне header.php, а затем завершить элементы в шаблоне footer.php .
Это немного упрощенный пример, поскольку он относительно распространен, но этот принцип остается верным и в других файлах.
С учетом сказанного есть простая стратегия, которую мы можем использовать для комментирования нашего кода:
Элементы HTML обычно имеют одну из четырех форм:
- Элемент не будет содержать идентификатор или класс
- Элемент будет содержать только идентификатор
- Элемент будет включать только класс
- Элемент будет включать в себя как идентификатор, так и класс
Для каждой из этих перестановок я следую следующим соглашениям:
Нет идентификатора или класса
|
1
2
3
4
5
6
|
<form method=»post» action=»options.php»>
<?php
/* Snipped for brevity */
submit_button();
?>
</form>
|
Выше приведен фрагмент кода для формы, которая используется для сохранения параметров в форме базы данных WordPress на панели инструментов. В этом случае я обычно оставляю комментарий в конце элемента, который указывает назначение формы или некоторый другой атрибут, такой как атрибут действия.
Учитывая эту стратегию, приведенный выше пример может выглядеть примерно так:
|
1
2
3
4
5
6
|
<form method=»post» action=»options.php»>
<?php
/* Snipped for brevity */
submit_button();
?>
</form><!— /options serialization —>
|
Или:
|
1
2
3
4
5
6
|
<form method=»post» action=»options.php»>
<?php
/* Snipped for brevity */
submit_button();
?>
</form><!— /options.php —>
|
Соглашение, которое я предпочитаю использовать, состоит в том, чтобы использовать обратную косую черту — обычным способом HTML — с последующей целью описания элемента, чтобы сообщить мне, что я заканчиваю элемент.
Хотя это может быть не особенно полезно для одного изолированного элемента, я обнаружил, что он полезен для вложенных элементов, а также для случаев, когда элемент, например контейнер, разделяется на файлы.
Только идентификатор
В случае, если элемент имеет идентификатор, я использую следующий комментарий:
|
1
2
3
|
<div id=»wrapper»>
<!— nested elements removed —>
</div><!— /#wrapper —>
|
Как и выше, я использую обратную косую черту, за которой следует знак « # », который представляет идентификатор в CSS, за которым следует имя значения атрибута идентификатора. Это даст мне знать, что я заканчиваю элемент с заданным идентификатором.
Опять же, это наиболее полезно, когда элемент существует в файлах, но также полезно, когда вам нужно выполнить глобальный поиск в файлах шаблонов или в файлах CSS.
Только класс
Когда элемент включает в себя только класс (или набор классов), я придерживаюсь той же стратегии, что и выше — я использую обратную косую черту, индикатор CSS для класса, а затем класс (или первый класс) для элемента:
|
1
2
3
|
<div class=»container»>
<!— nested elements removed —>
</div><!— /.container —>
|
Достаточно просто.
И удостоверение личности и класс
Но что происходит, когда элемент включает в себя как идентификатор, так и класс? Поскольку идентификаторы уникальны, а имена классов — нет, я всегда по умолчанию использую идентификатор элемента при завершении комментария:
|
1
2
3
|
<div id=»post-meta» class=»post-meta-data meta-link pull-right»>
<!— PHP snipped for brevity —>
</div><!— /#post-meta —>
|
Имеет смысл, верно? И все еще остаётся вопрос: это позволяет легко узнать, какой элемент у меня заканчивается, и легко найти его в остальных файлах проекта.
JavaScript
JavaScript похож на PHP в том, что он поддерживает функции более высокого порядка, такие как функции (и прототипы, если вы пишете ванильный JavaScript). Из-за этого полезно иметь соглашение, согласно которому мы документируем наши функции.
Вот в чем дело: WordPress по умолчанию включает в себя jQuery , поэтому большинство JavaScript-сценариев, написанных на WordPress, обычно пишутся с использованием комбинации JavaScript-кода на основе jQuery и ванильных функций, таких как функции.
Следующие стратегии оказались полезными при написании JavaScript в WordPress:
Опишите цель
Во-первых, я пытаюсь назвать файл в зависимости от цели, для которой он служит (например, navigation.js или theme.js или admin.js ).
Во-вторых, я также предоставлю краткое описание в верхней части каждого файла, используя соглашения PHPDoc для описания файла и того, как долго он был частью проекта:
|
1
2
3
4
5
6
7
8
|
/**
* admin.options.js
*
* Manages the event handlers for several elements on the Dashboard options page.
*
* @since 1.0
* @version 3.2
*/
|
Документирование функций
Для функций я придерживаюсь соглашения, аналогичного приведенному выше, в котором я приведу краткое описание функции, опишу, что она принимает и что она возвращает, а также сколько времени это было в проекте и текущую версию файла:
|
01
02
03
04
05
06
07
08
09
10
|
/**
* Helper function that’s fired when the user clicks ‘Done’ or hits ‘Enter’
* when working to save their social icons.
*
* @param $ A reference to the jQuery function
* @param evt The source event of this handler
* @returns Whether or not the user hit enter or cancel to save their options.
* @since 1.0
* @version 1.2
*/
|
На линии и блоки
На самом деле это не более чем стандартные комментарии кода, которые часто используют большинство разработчиков. Существует однострочный вариант, многострочный вариант и цель, которой они служат: то есть просто описать, что должно произойти в коде после комментария.
|
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
|
/*
* If we’re looking at the RSS feed icon, disable the input
* and link the user to the Global options for where to set it.
*/
if ( » !== sRssUrl ) {
$(‘#social-icon-url’)
.val(sRssUrl)
.attr(‘disabled’, ‘disabled’);
} else {
$(‘#social-icon-url’).removeAttr(‘disabled’);
} // end if
|
К этому мало что можно добавить, чего я не освещал в первой статье, но я действительно хотел упомянуть об этом здесь для обзора и для завершения.
Инструменты документации?
Хотя нет официального инструмента документирования JavaScript, jsDoc стала одной из самых распространенных утилит для документирования кода JavaScript.
Stylesheets
Комментировать CSS-файлы гораздо проще, чем работать с PHP или с разметкой, потому что на самом деле есть только один способ написания стилей.
То есть вы определяете стили для элемента, используя идентификатор или класс:
|
1
2
3
4
5
6
|
#no-comments {
font-size: 24px;
line-height: 36px;
font-weight: bold;
color: #444;
}
|
Или:
|
01
02
03
04
05
06
07
08
09
10
|
.home .sticky:before {
display: inline-block;
background: transparent url(images/sticky.png) no-repeat;
width: 58px;
height: 45px;
content: «»;
position: absolute;
top: 26px;
left: -9px;
}
|
Вообще говоря, я не думаю, что вам нужно комментировать стили, но если вы окажетесь в ситуации, когда завершающая скобка находится за пределами экрана, то может быть полезно завершить стиль комментарием, подобным этому:
|
1
2
3
4
5
6
|
#no-comments {
font-size: 24px;
line-height: 36px;
font-weight: bold;
color: #444;
} /* #no-comments */
|
Или:
|
01
02
03
04
05
06
07
08
09
10
|
.home .sticky:before {
display: inline-block;
background: transparent url(images/sticky.png) no-repeat;
width: 58px;
height: 45px;
content: «»;
position: absolute;
top: 26px;
left: -9px;
} /* .home .sticky:before */
|
Как насчет препроцессоров?
Прямо сейчас использование таких языков, как LESS и Sass, и их соответствующих препроцессоров становится все более популярным в веб-разработке. Одной из наиболее распространенных особенностей этих двух языков является то, что они поддерживают вложенные правила.
В этом случае, я думаю, есть гораздо более веские аргументы в пользу использования комментариев. Например:
|
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
|
#header {
#slideshow {
#image-list {
list-style: none;
float: left;
margin: 0;
width: 100%;
} // #image-list
} // #slideshow
} // #header
|
Таким образом, вы знаете, какой элемент вы заканчиваете, независимо от того, где этот элемент начинается в IDE.
Вывод
В этой серии я обрисовал, почему я считаю, что комментарии к коду должны быть тем, что все разработчики должны включать в свой код. В этой статье я обсудил мои стратегии для того, как я комментирую свою разметку, мой JavaScript и мои стили.
Хотя я не говорю, что мой способ — это единственный способ писать комментарии — это всего лишь один способ — я верю, что включение комментариев имеет большое значение для того, чтобы сделать проект более понятным для вас и ваших коллег, и я думаю, что включение их в Ваша работа — это то, к чему должен стремиться каждый разработчик.
Надеюсь, что эта серия послужила основанием именно для этого. Независимо от того, я хотел бы услышать ваши мысли и предложения в комментариях.