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

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

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

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

Чрезмерно резкий, но это объясняет две точки сразу.

1. Запись Ваш код хорошо.
2. Комментарий это так Вы и другие знаете то, что это означает.

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

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

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

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

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

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

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

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

Меньше больше.

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

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

, Например:

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

}

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

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

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

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

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

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

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

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

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

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

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

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

"blabla comment the why not the what blabla"

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

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

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

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

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

С более субъективной точки зрения,