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

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

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

Да, это произошло со мной, и я комментирую полностью теперь.

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

Также показывают им преимущество чего-то как SandCastle.

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

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

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

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

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

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

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

Гарантируют, что это - РАССМОТРЕННЫЙ комментарий, что Вы выигрываете на, поскольку пассивно-агрессивный devs зарегистрирует каждый последний оператор как not-so-subtle FU.

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

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

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

"При записи Кода" = "Запись последовательности команд на специальном языке" + "Пишущие комментарии"

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

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

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

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

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

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

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

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

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

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

Мое мнение:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Зависит от того, сколько власти Вы имеете...

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

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

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

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

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

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

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

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

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

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

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

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

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

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