Как убедить людей комментировать свой код [закрыто]

https://stackoverflow.com/questions/159597

03-07-2019
|

Вопрос

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

Я заметил, что многие программисты предпочитают воспринимаемую скорость написания кода без комментариев оставлять часть документации для себя и других.Когда я пытаюсь убедить их, я слышу недоделанные вещи вроде "имя метода / класса должно указывать, что оно делает" и т.д.Что бы вы сказали им, чтобы они изменили свое мнение?

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

Другими связанными с этим вопросами являются: Комментирующий код, Комментируете ли вы свой код и Как бы вам понравились ваши комментарии.

Решение

Лучший способ убедить человека - заставить его осознать это самостоятельно.Заставьте их отлаживать хорошо прокомментированный код.Это покажет им, как выглядит хороший комментарий - комментарии бесполезны, если они действительно не передают релевантную информацию (которая обычно является "почему", потому что код описывает "что").Они заметят, как это просто.Затем позвольте им вернуться к некоторым элементам своего старого кода.Они заметят, как это тяжело.Вы не только показали им, чего не следует делать, но и что нужно делать (это более важно).Тебе больше ничего не нужно делать.Более того, вам не нужно пытаться убедить их устно.Они просто должны понимать необходимость комментировать код по-своему.Это, конечно, при условии, что код, который необходимо прокомментировать, не говорит сам за себя.

Другие советы

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

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

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

Мое мнение:

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

Я любитель комментировать "почему", а не "что".Если непонятно, почему код использует один подход вместо другого, прокомментируйте это.Если вам пришлось добавить взломанную неиспользуемую переменную, чтобы обойти ошибку компилятора, прокомментируйте, почему.Но комментарии типа "// Подключиться к базе данных" являются признаками плохого кода или неправильной политики.Метод с именем ConnectToDatabase() намного лучше.И если в нем есть "//Определить IP сервера базы данных", возможно, это следует перенести в метод с именем "DetermineDbServerIPAddress()".

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

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

Дайте им немного (минимум ~ 500 строк) ужасного, раскомментированного спагетти-кода для рефакторинга.Убедитесь, что переменные не имеют логических имен.Пробелы необязательны.

И посмотрите , как они нравится!

Чересчур жестко, но это дает два очка за один раз.

Напишите свой код хорошо.
Прокомментируйте это так, чтобы вы и другие знай, что это значит.

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

Одна заключительная правка:Комментарий Качество это тоже довольно важно.У некоторых разработчиков соотношение количества кода и комментариев в их работе составляет почти 2: 1, но это не делает их хорошими комментариями.У вас может быть на удивление мало комментариев в вашем коде, и все равно это будет иметь большой смысл.

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

Напомните им, что чтение кода может рассказать им только о том, что это за код. делает, не то , что это есть на самом деле предполагаемый делать.

Если вы или другие разработчики не прочитали код полностью (или Код Завершен 2) но затем прекратите то, что вы делаете, и прочтите это.

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

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

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

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

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

Стоит также иметь в виду, что многие хорошие разработчики предпочитают писать четкие C #, Java, что угодно, чем гораздо менее точные человеческие языки со всеми присущими им допущениями и двусмысленностями.Правда, большинство людей со здравым смыслом знали бы, что детализации достаточно, но хорошие разработчики - это не "большинство людей".Вот почему в итоге мы получаем комментарии типа \\adds a to b and store it in c (ладно, это слишком экстремально, но вы поняли, в чем дело).

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

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

Серьезно, некоторые люди предполагают, что вы можете читать их мысли.

Если вы являетесь частью гибкой команды, код является коллективной собственностью, поэтому, когда вы видите код без комментариев, неуклюжий или трудночитаемый, продолжайте изменять (рефакторинговать) его, чтобы вы его понимали.Если люди жалуются, скажите им, почему, и будьте откровенны.Что вы сочли это непонятным, и никто не владеет этим кодом.

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

Я бы сказал: "вчера мне пришлось прочитать кое-что из вашего кода.Я был в состоянии понять это, но меньше или равное 5 хорошо подобранным строкам комментария, объясняющего, как он достиг своих целей, позволило бы мне прочитать это примерно за одну десятую времени, и тогда я мог бы вместо этого беспокоиться о понимании проблемы.Я не глуп, и ты не умнее, потому что можешь писать вещи, которые трудно понять.Напротив, если вы не можете создавать читаемые наборы документации + кода, то вы в меньшей степени разработчик ".

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

Были аналогичные дискуссии по поводу комментариев.Вот один из них о том, каким правилам люди следуют при комментировании кода: Каковы ваши "жесткие правила" относительно комментирования вашего кода?.В некоторых ответах также есть очень веские причины, по которым вы хотели бы прокомментировать свой код.

Проявите мудрость в своем желании получить комментарии, и они с большей вероятностью прислушаются.

Меньше значит больше.

Делайте упор на качество, а не на количество.

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

Например:

/// <summary>
/// Gets the Person.
/// </summary>
/// <returns>
/// A Person
/// </returns>
public Person GetPerson()
{

}

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

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

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

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

class User {
    getUserName() { /* code here */ }
}

Какой смысл добавлять заголовок функции к приведенному выше фрагменту кода?Что еще ты собираешься сказать, что besdies "получает имя пользователя".Не весь код нуждается в комментариях.Мое эмпирическое правило таково:пропустите комментарии, если вы не добавляете никакой полезной информации, которой нет в сигнатуре функции.

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

При написании кода я, как правило, достаточно подробно комментирую, как нечто само собой разумеющееся.Затем я возвращаюсь к просмотру и пытаюсь удалить как можно больше комментариев, не снижая понятности кода.> в 80% случаев это так же просто, как извлечь хорошо названный метод, обычно это приводит к комментарию, который просто дублирует информацию в самом коде.Кроме того, если есть раздел кода, который "нуждается" в комментарии, я ищу способы упростить его или сделать более понятным.

Код должен быть самодокументируемым и с правильные методы вы можете довольно легко проделать 95% пути туда.Как правило, я считаю это ошибкой, если остаются какие-либо комментарии к коду, который я проверяю.

Зависит от того, сколько у вас энергии...

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

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

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

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

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

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

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

Что ж, всегда существует подход "если вы не будете комментировать свой код, мы найдем кого-нибудь другого, кто прокомментирует их".

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

"Написание кода" = "Написание последовательности команд на специальном языке" + "Написание комментариев"

Это должно быть самоочевидно комментировать код во время его написания!Вы когда-нибудь комментировали код, которому уже 3 или 4 месяца?(Конечно, у вас есть, и это было что угодно, только не веселье!)

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

@Джеймс Карран, я согласен на 100%!Я могу прочитать ваш код и понять, что вы сказали компилятору делать;но это не значит, что вы намеревались заставить компилятор сделать это.Я знаю, что я не настолько самонадеянный программист, чтобы верить, что каждый раз, когда я пишу код, он делает именно то, что я пытался заставить его делать.Кроме того, я часто обнаруживаю, что это помогает мне выявлять глупые логические ошибки в моем коде, просматривая его после того, как я написал его, и пытаясь объяснить, что я намеревался сделать с кодом.

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

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

Я использую один тонкий прием:

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

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

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

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

В противном случае (при условии, что вы супервайзер / менеджер) сделайте это частью их служебной аттестации.Если вы можете измерить это, вы можете оценить, основываясь на этом.

Убедитесь, что вы оцениваете именно РЕЦЕНЗИРУЕМЫЙ комментарий, поскольку пассивно-агрессивные разработчики задокументируют каждое последнее утверждение как не очень тонкое "ФУ".

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

В вашем случае просьба к вашим не комментирующим разработчикам потратить час или два на объяснение своего кода, возможно, для "медленной" аудитории, возможно, во время обеденного перерыва, "чтобы избежать проскальзывания проекта", будет иметь большое значение.Умные люди - даже упрямые - быстро учатся!

На мой взгляд (и я говорю о .Сетевое программирование здесь), если вам нужно добавить комментарий, вам не удалось сделать код читабельным.Ответом обычно является рефакторинг!

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

Запись того, что будет делать метод / класс, прежде чем на самом деле его кодировать, очень помогает сделать это правильно - и вы прокомментировали это.

Нанимайте только хороших инженеров, которые гарантируют, что в их коде неявно указано намерение (с использованием комментариев и иным образом).Любой, кто хочет получить работу, должен делать это правильно.Сурово, но справедливо, ИМХО.

Лицензировано под: CC-BY-SA с атрибуция

Не связан с StackOverflow