Остановите меня, если вы слышали это раньше …
В 20+ годах написания кода для жизни это одна фраза, которую я слышал больше всего.
Это клише.
И, как и многие клише, у него есть ядро правды. Но эта правда была настолько оскорблена тем, что большинство людей, которые произносят фразу, не имеют идеи, что это действительно значит.
Это правда? Да Отказ
Значит ли это, что вы никогда не должны комментировать ваш код? Нет Отказ
В этой статье мы посмотрим на хорошие, плохие, а уродливое, когда дело доходит до комментирования вашего кода.
Для начала есть два разных типа кода комментариев. Я называю их Документация Комментарии и Разъяснение Комментарии Отказ
Документация Комментарии
Комментарии документации предназначены для всех, кто может потреблять ваш исходный код, но вряд ли прочитать через него. Если вы строите библиотеку или рамку, которые будут использовать другие разработчики, вам нужна форма документации API.
Дальше удаленное из исходного кода ваша документация API, тем больше вероятность того, чтобы устареть или неточность со временем. Хорошая стратегия смягчить это – это встроить документацию непосредственно в код, а затем использовать инструмент для его извлечения.
Вот пример комментариев документации из популярной библиотеки JavaScript под названием Лоташ Отказ
Если вы Сравните эти комментарии к их онлайн-документации Вы увидите, что это точное совпадение.
Если вы пишете комментарии документации, вы должны убедиться, что они следуют последовательному стандарту, и что они легко отличаются от любых комментариев уточнения, которые вы также можете добавить. Некоторые популярные и хорошо поддерживаемые стандарты и инструменты включают Jsdoc Для JavaScript, Docfx для dotnet, а Javadoc для Java.
Недостатком подобных комментариев является то, что они могут сделать ваш код очень «шумным» и сложнее читать для всех, кто активно участвует в поддержании его. Хорошая новость в том, что большинство редакторов кода поддерживают «складку кода», что позволяет нам свернуть комментарии, поэтому мы можем сосредоточиться на коде.
Разъяснение комментарии
Уточнения комментариев предназначены для всех (включая ваше будущее Self), который может потребоваться сохранить, рефакторировать или расширить свой код.
Часто уточнение комментариев является кодовым запахом. Это говорит вам, что ваш код слишком сложен. Вы должны стремиться удалить разъяснения комментарии и упростить код вместо этого, потому что «хороший код – это самодоступность».
Вот и Пример плохой – хотя очень интересно – разъяснение комментариев.
/* * Replaces with spaces * the braces in cases * where braces in places * cause stasis.**/ $str = str_replace(array("\{","\}")," ",$str);Вместо того, чтобы украшать слегка запутанное заявление с умной рифмой – в Димометр амфибрах , не меньше – автор был бы намного лучше, проводить время на функцию, которая облегчает чтение и понимание кода. Может быть, функция имена, RemoveCurlybraces вызывается из другой функции имени SanitizeInput ?
Не поймите меня неправильно, есть времена – особенно когда вы проходите через дробильную нагрузку – где впрыскивая немного юмора может быть хорошим для души. Но когда вы пишете забавный комментарий, чтобы составить плохой код, он на самом деле делает людей менее склонными к рефактору и исправить код позже.
Вы действительно хотите стать ответственным за грабитель всех будущих кодеров радости читать этот умный маленький рифму? Большинство кодеров обмениваются и двигались, игнорируя запах кода.
Есть также времена, когда вы сталкиваетесь с комментарием, который является избыточным. Если код уже прост и очевиден, нет необходимости добавлять комментарий.
Вроде, не делай эту ерунду:
/*set the value of the age integer to 32*/int age = 32;
Тем не менее, есть времена, когда независимо от того, что вы делаете с самим кодом, разъяснительный комментарий все еще гарантирован.
Обычно это происходит, когда вам нужно добавить некоторого контекста на неинтекодивное решение.
Вот хороший пример от Lodash:
function addSetEntry(set, value) { /* Don't return `set.add` because it's not chainable in IE 11. */ set.add(value); return set; }Есть также раз, когда – после многих мыслей и экспериментов – оказывается, что, казалось бы, наивное решение проблемы на самом деле лучшее. В этих сценариях практически неизбежно, что какой-то другой код кодера придет, думая, что они намного умнее, чем вы, и начните возиться с кодом, только чтобы обнаружить, что ваш путь был лучшим способом все время.
Иногда другой кодер – это ваше будущее я.
В этих случаях лучше всего спасать все время и смущение и оставить комментарий.
Следующий комментарий Mock Захватывает этот сценарий идеально:
/**Dear maintainer: Once you are done trying to 'optimize' this routine,and have realized what a terrible mistake that was,please increment the following counter as a warningto the next guy: total_hours_wasted_here = 42**/
Опять же, вышеизложенное больше о том, чтобы быть смешным, чем полезным. Но вы должны оставить комментарий, предупреждаю, как другие не преследуют некоторое, казалось бы, очевидное «лучшее решение», если вы уже пробовали и отклонили его. И когда вы делаете, комментарий должен указать, какое решение вы пытались, и почему вы решили против этого.
Вот простой пример в JavaScript:
/* don't use the global isFinite() because it returns true for null values*/Number.isFinite(value)
Уродливый
Итак, мы смотрели на добро и плохое, но как насчет уродливых?
К сожалению, есть времена в любой работе, где вы расстраиваетесь и когда вы пишете код для жизни, можно заманчиво отказать это разочарование в кодовых комментариях.
Работайте с достаточным количеством баз кода, и вы столкнетесь с комментариями, которые варьируются от циничных и удручающих до темных и среднего возраста.
Такие вещи, как казалось бы безвременные …
/*This code sucks, you know it and I know it. Move on and call me an idiot later.*/
/* Class used to workaround Richard being a f***ing idiot*/
Эти вещи могут показаться смешными или могут помочь отпустить немного разочарования в данный момент, но когда они делают его в производственный код, они в конечном итоге заставляют кодер, который писал их, и их работодатель выглядит непрофессиональным и горьким.
Не делай этого.
Если вам понравилась эта статья, пожалуйста, разбейте значок аплодисментов куча раз, чтобы помочь распространить слово. И если вы хотите прочитать больше всего, пожалуйста, подпишитесь на еженедельный рассылку Mastley Dev Mastery ниже.
Оригинал: “https://www.freecodecamp.org/news/code-comments-the-good-the-bad-and-the-ugly-be9cc65fbf83/”