Как убедить людей прокомментировать их код

Ответ 1

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

Ответ 2

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

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

Ответ 3

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

Ответ 4

Мое мнение:

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

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

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

Ответ 5

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

Ответ 6

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

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

Слишком суровый, но он получает две точки за один раз.

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

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

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

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

Ответ 7

Напомните им, что чтение кода может только сказать им, что делает код, а не то, что он должен делать.

Ответ 8

Если вы или другие разработчики не прочитали Code Complete (или Code Complete 2), а затем остановите то, что вы делаете, и прочитайте его.

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

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

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

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

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

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

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

Ответ 9

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

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

Ответ 10

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

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

Ответ 11

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

Ответ 12

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

Ответ 13

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

Меньше.

Подчеркните качество по количеству.

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

Например:

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

}

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

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

Ответ 14

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

Ответ 15

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

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

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

Ответ 16

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

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

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

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

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

Ответ 17

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

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

Ответ 18

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

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

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

Ответ 19

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

Ответ 20

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

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

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

Ответ 21

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

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

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

Ответ 22

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

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

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

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

Ответ 23

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

Ответ 24

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

Ответ 25

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

Ответ 26

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

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

Убедитесь, что это ОБНОВЛЕННОЕ комментирование, на которое вы набираете, поскольку пассивно-агрессивные разработчики будут документировать каждое последнее утверждение как не очень тонкое FU.

Ответ 27

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

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

Ответ 28

"blabla комментировать, почему не то, что blabla"

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

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

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

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

Последнее в этом: я никогда не терял времени на чтение комментариев, и они часто сокращали мое время обучения. Я никогда не видел "слишком прокомментированный" код. Я часто читал комментарии, которые мне не были полезны (как и все), но я никогда не думал "если бы только я все это время читал комментарии, делая что-то более полезное!". Учитывая тот факт, что все современные IDE предоставляют возможность скрывать большие комментарии, я не понимаю, почему это может считаться плохим, чтобы написать бесполезный комментарий.

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

Я предпочитаю бесполезный комментарий в очевидной части кода, чем ничего в темном методе на 15 страниц....

Ответ 29

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

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

Ответ 30

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