Как комментировать свой код как профессионал: передовой опыт и хорошие привычки

Написание кода во многом похоже на написание прозы. Каждый человек делает это немного по-своему, и из-за этого у всех нас есть отчетливый голос, когда наш код читается. У нас разные соглашения об именах и разная логика решения проблем. Мы все думаем, что наш код имеет смысл, особенно если он работает, но кто-то другой может нет. Чтобы бороться с этим, нам всем нужно научиться комментировать исходный код. Таким образом, у любого, кто придет рядом с проектом, будет четкий путь к пониманию и улучшению / исправлению нашего кода.

Как комментировать код - основы

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

/** Body Element Styling **/

body {color:red;}

h1 {size:17px;}


/** Sidebar Widget Styling**/

#email-signup-1 {text-transform:uppercase;}

Каждый язык программирования имеет свой способ комментирования в исходном коде. PHP, HTML, JavaScript и C # имеют немного разные символы в начале и конце кода. Хотя есть и некоторые языковые практики, их больше разделяют, чем нет.

Мы обсудим некоторые из различных типов комментариев, с которыми вы столкнетесь, их использование и лучшие практики (или, может быть, просто полезные привычки) при их использовании самостоятельно.

Основные принципы комментирования кода просты:

• Сделайте их краткими
• Держите их актуальными
• Используйте их обильно, но не в избытке

Если вы можете помнить об этом, у вас все будет в порядке.

Момент для обсуждения скептиков

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

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

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

Документация блока заголовка

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

Это плохая привычка. Потому что это бессмысленно. Что ж, это действительно бессмысленно.

Также посмотрите на приведенный выше пример: заголовок комментария абсурдно длинный. Для этого есть очень редкие причины. Так что не надо.

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

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

Когда комментарии в заголовке полезны

Комментарии заголовка полезны в исходном коде для простого объяснения того, чего ожидать в этом файле. Например, это сценарий, который поставляется с движком разработки игр под названием RPG Maker, а основной JS-файл, который управляет каждой игровой сценой, начинается следующим образом:

//=============================================================================
// rpg_scenes.js v1.6.2
//=============================================================================

//=============================================================================

/**
 * The Superclass of all scenes within the game.
 * 
 * @class Scene_Base
 * @constructor 
 * @extends Stage
 */
function Scene_Base() {
    this.initialize.apply(this, arguments);
}

Scene_Base.prototype = Object.create(Stage.prototype);
Scene_Base.prototype.constructor = Scene_Base;

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

Встроенная документация

Самый распространенный тип комментария исходного кода - это встроенный комментарий. Между ними есть тонкая грань между тем, чтобы делать все правильно, выходить за рамки или слишком бережно относиться к ним. Это баланс, который вам нужно просто изучить с течением времени, но есть несколько довольно хороших практических правил, которые следует учитывать.

Не делайте построчных комментариев. Встроенный комментарий - это одно. Построчные комментарии делают код почти нечитаемым. См. ниже:

function sourceCodeComment () { //calls a function
  var comment = document.getElementbyID("Code Comment").value; // declares a variable
  if (comment != null && comment != '') {  //starts an if statement to evaluate if there's a comment
        return console.log("Thank you for your comment.") //prints a string to the console
}

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

Если вы чувствуете, что это необходимо задокументировать, этого будет достаточно.

//checks to see if there's a comment. If so, returns a thank you message.

function sourceCodeComment () {
  var comment = document.getElementbyID("Code Comment").value; 
  if (comment != null && comment != '') { 
        return console.log("Thank you for your comment.")
}

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

Можно помещать предупреждения в комментарии к исходному коду

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

Или, может быть, в будущем появится что-то еще, и они попытаются вызвать функцию, которая сломает все и поставит проект на колени.

В любом случае, если у вас есть что-то, что, как вы знаете, не сработает, и что вы знаете, что другие люди, вероятно, попытаются это сделать в будущем, можно предупредить их об этом.

// Don't bother trying to use goodCodeComment() here. 
// It breaks bestPractices() despite seeming like the best option.
// We went with simplyOkayCodeComment() instead.

function simpleOkayCodeComment() {
	//some kind of code goes here
}

Кроме того, вы заметили, что мы сделали в этом примере? Мы не только предупредили будущих разработчиков, но и добавили комментарий-заполнитель в середине функции. Поскольку комментарии в исходном коде игнорируются, вы можете использовать их для сохранения текста-заполнителя в файле (своего рода как аннотацию для себя, чтобы вернуться туда, или как пример для кого-то в качестве объяснения).

Не будь придурком

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

//This function looks like it was written by a third grader.
//It shouldn't work, but it does somehow. I don't want
//to fix it because I want you all to see how bad it is.

Или, может быть, они исправляют код, но включают код, просто закомментированный, чтобы они могли показать свой код, в то же время высмеивая предыдущего автора.

//The old code was so bad, I just had to leave it here for you to see.
//I fixed it. My code is below. But look at this.

// function theMatrix() {
//	var neo = maybeTheOne.data + theOracle.data
//	if theOne() !== neo
//		return console.log("you got the gift, but it looks like you're waiting for something")
// }

Только убедитесь, что вы никогда этого не сделаете. Даже если вы думаете, что ведете себя забавно или что это заставляет вас хорошо выглядеть, это не так, и это не так.

Реальное использование закомментированного кода состоит в том, чтобы вы держали этот код под рукой, пытаясь что-то еще. Или привести пример того, что раньше не работало, чтобы кто-то не пробовал снова безрезультатно.

Комментарии к исходному коду для WordPress

В целом WordPress работает на четырех разных языках. HTML, CSS, PHP и JavaScript. Обязательно убедитесь, что в комментариях используются правильные символы.

Для HTML:

<!-- comments go here and can be single or on multiple lines --></em>

В CSS:

/* Any number of lines will be a comment until the comment is closed */ 

И PHP, и JavaScript имеют одни и те же методы для создания однострочных и многострочных комментариев:

<?php function(); // a single line comment is like this ?>

или

<?php /* unlike above, you can carriage return
				and no matter how many lines you use,
					the comment won't stop until closed */

Заключение

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

Каковы ваши советы и рекомендации, как получить максимальную отдачу от комментирования кода?

Статья из избранного изображения от Skillup / shutterstock.com