Почему компания должна создать атмосферу, которая препятствует кодовым комментариям? [Дубликат]

    

У этого вопроса уже есть ответ:

    

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

Тем не менее, я в компании, где большая часть кода, с которым я сталкиваюсь, не имеет комментариев. Почему программист не пишет комментарии? Существуют ли какие-либо объективные причины? Как вы думаете, комментарии раздражают, когда вы читаете код других? Я тоже не пишу комментариев, и я могу думать о некоторых причинах, почему бы и нет:

  1. Потому что я уже могу легко понять программу.
  2. Моему боссу все равно, как моя программа выполнит свою работу.
  3. Никто не сможет забрать мою программу после моего ухода.

Цель комментариев, как правило, включать объяснения для программы, однако я обнаружил, что в моей компании комментарии используются для покрытия устаревшего кода. Например:

/* Obsolete code */
New code

Как вы относитесь к комментариям? Должны ли мы это сделать? Или это зависит от ситуации?

30 голосов | спросил 6 revs, 5 users 44%
lamwaiman1988
1 Jam1000000amThu, 01 Jan 1970 03:00:00 +030070 1970, 03:00:00

17 ответов


45

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

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

int x ; // Integer x 
// Copy the string bob into fred making sure not to overflow the buffer. 
strncpy(bob, fred,sizeof(bob));  

(Ошибка намерена сделать точку)

Однако разработчики, добавляющие слишком мало комментариев, так же распространены ......

ответил fr13d 20 J0000006Europe/Moscow 2016, 15:35:33
26

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

То, что вы пытаетесь документировать, - это логический поток кода, а не подробные данные. Например:

writer = csv.DictWriter(open(args.out, 'wb'), output[0].keys(), dialect='excel')
writer.writeheader()
for row in output:
    writer.writerow(row)
writer.close()
del writer

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

# Dump found entries into a CSV file for Excel
writer = csv.DictWriter(open(args.out, 'wb'), output[0].keys(), dialect='excel')
writer.writeheader()
for row in output:
    writer.writerow(row)
writer.close()
del writer

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

ответил fr13d 20 J0000006Europe/Moscow 2016, 15:35:33
14

Проблема начинается с людей, которые считают, что комментарии объясняют код . Тогда это очень легкий прыжок «зачем беспокоиться о комментировании», а затем «мы не комментируем здесь».

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

/* setting foo to 1 here so that biz doesn't run too many times 
 * changed from 6 on 3-Aug-11 for ticket 1234
 */
foo = 1; 

Это, я думаю, то, что должно быть (но не) объяснено в школе.

ответил fr13d 20 J0000006Europe/Moscow 2016, 15:35:33
12

Я работал однажды в компании, которая не поощряла слишком много комментариев. Хотя это было для Ruby on Rails . Ruby - очень выразительный язык, а структура Ruby on Rails четко определяет, где вещи принадлежат и для чего они хороши. Поэтому использование комментариев в контроллере для объяснения того, какой метод подходит, было бы ненужным. Это может зависеть от используемого вами контекста и языка. Многое можно объяснить, используя дескриптивные имена для методов и переменных. Это может даже заставить вас держать методы маленькими и иметь одну, четко определенную цель. Если трудно найти хорошее имя для метода, это, скорее всего, потому, что вещь делает слишком много и должна быть разделена на более мелкие части.

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

ответил fr13d 20 J0000006Europe/Moscow 2016, 15:35:33
9

Комментарии полезны, когда цель кода не сразу очевидна.

Возможно, код можно было бы уточнить, возможно, нет.

Возможно, это очевидно для вас, но не для кого-то другого.

Это вызов для решения .

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

ответил fr13d 20 J0000006Europe/Moscow 2016, 15:35:33
7

Я бы сказал, это зависит от ситуации. Когда код не слишком эзотерический и имена переменных хорошо выбраны, чтобы код был «самодокументирован», тогда комментарии могут быть необязательными. Но когда намерение не ясно, просто взглянув на код (например, при использовании какой-то неясной математической теоремы), тогда хороший комментарий объясняет, почему.

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

Что касается вашего дела, другие разработчики иногда должны смотреть код друг друга? Вы никогда не слышали ни одного из них (или себя): «Что делает этот код? Я ничего не понимаю!». Если это так, возможно, требуется хороший комментарий.

ответил fr13d 20 J0000006Europe/Moscow 2016, 15:35:33
6

Комментарии прекрасны, если они используются только тогда, когда это необходимо, и они объясняют то, что не очевидно. Примеры mattnz делают это понятным. Нет ничего, что не было бы очевидно в этой части кода, поскольку оно просто использует уже задокументированные функции. Так, например, выполнив man strncpy, вы можете узнать все об этой функции. Не помещать комментарии в такой код гораздо лучше и менее запутанным для других программистов.

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

ответил fr13d 20 J0000006Europe/Moscow 2016, 15:35:33
5

В основном есть две категории комментариев:

  • Комментарии, объясняющие код
    Как отмечали другие, код и комментарии имеют тенденцию дрейфовать друг от друга. Вы можете оставить комментарий перед блоком кода, но с течением времени код изменяется, и никто не обновляет комментарий, чтобы отразить изменения. Комментарий становится ложью.
    Если вы действительно чувствуете, что блок кода нуждается в комментарии для объяснения намерения кода, то вы можете сделать это, чтобы извлечь блок кода в метод и присвоить ему имя . Тогда имя станет объяснением. И имена методов не дрейфуют так же, как и комментарии. Никто не любит называть метод «GetData», который фактически сохраняет некоторые данные вместо этого. Либо разработчик изменил бы название метода, либо увидел, что изменения, которые они собираются сделать, вообще не принадлежат.
    Однако есть некоторые вещи, которые не могут быть частью имени. Например, почему вы выбрали этот алгоритм над другим, или почему то, что кажется более очевидным решением проблемы, не подходит в данном конкретном случае и т. Д. Существуют и другие случаи, когда имя хочет содержать все, что нужно знать о коде. Если у вас есть хороший набор модульных тестов (и вы должны), набор тестов будет частью объяснения как намерения, так и внутренней работы кода. Именование ваших тестов так же важно, как именование вашего производственного кода.

  • Комментарии отключить код
    При написании нового кода его часто «утешительно», чтобы поддерживать старый алгоритм для справки, через некоторое время код, как правило, загроможден с небольшими или большими блоками кода, отключенными комментариями. Это делает код более трудным для чтения, а читатель должен учитывать, подходит ли код или нет .
    Нет необходимости в комментариях этого типа, так как каждое редактирование файла должно храниться в системе управления версиями в любом случае . Если вам нужно проверить, как алгоритм был в более ранней версии, вы должны быть в состоянии пойти туда и посмотреть. Каждая проверка должна содержать либо комментарий, описывающий намерение совершить код, либо ссылку на отчет об ошибке, либо что-то подобное.

Роберт К. Мартин написал книгу под названием « Чистый код ». Он посвятил целую главу комментариям в коде. Книга хорошая, и стоит денег и времени.
ответил fr13d 20 J0000006Europe/Moscow 2016, 15:35:33
4

В широком смысле мы пишем программное обеспечение для создания или добавления значения.

Комментарии, однако, не являются частью бинарной /исполняемой части программного обеспечения, они являются частью аспекта исходного кода программного обеспечения. Таким образом, они должны добавить значение в исходный код.

Комментарии, которые не добавляют значения, бессмысленны и неправильны.

Когда комментарии не соответствуют тому, что делает код, тогда программное обеспечение ошибочно и значение теряется.

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

Все остальное - это просто детали.

ответил fr13d 20 J0000006Europe/Moscow 2016, 15:35:33
4

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

Примечание для тех, кто не читал Sarcasm для действительно умных людей: неправильно комментирующий код непрофессиональный.

ответил fr13d 20 J0000006Europe/Moscow 2016, 15:35:33
3

В моем личном опыте комментарии полезны в двух случаях:

  1. объясните код следующему программисту (если вы уйдете)
  2. объясните код себе (когда вы имеете дело с тысячами файлов и не можете запомнить логику, лежащую в их основе).

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

Плюс, не программирование о принятии решений все время? Как вы могли вспомнить мотивы решения, если вы его не записываете?

Я рекомендую писать комментарии (даже против потока компании), потому что ваша производительность как-то зависит от нее.

ответил fr13d 20 J0000006Europe/Moscow 2016, 15:35:33
3

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

С другой стороны, иногда комментарии действительно не нужны (например, у тривиальных getters и seters в Java), и если компания создает официальную политику написания комментариев, программисты рискуют, что они будут вынуждены писать комментарии даже в таких ситуациях. Амбициозный менеджер также может задавать очень сложные шаблоны комментариев.

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

ответил fr13d 20 J0000006Europe/Moscow 2016, 15:35:33
3

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

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

Технический код низкого уровня может потребовать довольно много комментариев, поскольку его цель может быть скрыта за неочевидными техническими манипуляциями, сложными алгоритмами или использованием примитивных типов. Базовый пример: если метод возвращает int (который я бы не поощрял, но иногда операции нижнего уровня должны делать это) , без Javadoc -подобный комментарий к методу, который у вас нет способа узнать заранее, если возвращенный int это код ошибки, идентификатор ...

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

Еще одна мысль: не стоит недооценивать силу модульных тестов в качестве замены комментариев для целей документирования кода. Хорошо написанный блок-тест немедленно сообщает вам, какая ответственность за метод И является компилируемой И исполняемый файл.

ответил fr13d 20 J0000006Europe/Moscow 2016, 15:35:33
2
  

Почему программист не пишет комментарий, если есть какие-либо объективные   причины?

Комментарии требуют времени для написания и иногда могут быть приостановлены для другой работы с более высоким приоритетом. Разве у вас не были случаи, когда важнее было «git-r-done», чем комментировать то, что было сделано назад, когда?

  

Вы считаете, что комментарий раздражает, когда вы читаете код другого?

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

Мое общее мнение - комментарии хороши в модерации. Слишком много или слишком мало может быть большой проблемой.

ответил fr13d 20 J0000006Europe/Moscow 2016, 15:35:33
1

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

ответил fr13d 20 J0000006Europe/Moscow 2016, 15:35:33
0

С моей точки зрения, комментарии обычно должны ограничиваться комментариями уровня метода ( Javadoc или .NET Комментарии типа XML) для создания документации позже и комментариев TODO. Помимо этого, я думаю, что в большинстве случаев комментирование является излишним, отнимающим много времени и немного раздражающим. Если вы действительно думаете, что человек, который стоит за вами, не может понять это, тогда реорганизуйте его или, по крайней мере, поместите его в свой метод с комментарием уровня метода.

ответил fr13d 20 J0000006Europe/Moscow 2016, 15:35:33
0

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

Вне этих «вот почему это отстой» комментарии, если вы не можете понять, что он делает, просматривая код и читая /запуская тесты, тогда нет надежды.

ответил fr13d 20 J0000006Europe/Moscow 2016, 15:35:33

Похожие вопросы

Популярные теги

security × 330linux × 316macos × 2827 × 268performance × 244command-line × 241sql-server × 235joomla-3.x × 222java × 189c++ × 186windows × 180cisco × 168bash × 158c# × 142gmail × 139arduino-uno × 139javascript × 134ssh × 133seo × 132mysql × 132