Комментарии должны показать, какой код версии был добавлен/изменен для полезного?
Я использую венгерское Именование для кнопок Мне нравится элементов UI, текстовых полей и маркировок. Основное преимущество группирует в Visual Studio Всплывающее окно Intellisense. Если я хочу получить доступ к своим маркировкам, я просто начинаю вводить lbl...., и Visual Studio предложит все мои маркировки, приятно группировался.
Однако после выполнения все большего количества Silverlight и материала WPF, усиливая привязку данных, я даже больше не называю все свои средства управления, так как я не должен ссылаться на них от кода - позади (так как действительно нет никакого codebehind больше;)
11 ответов
Никакого значения. Если у вас есть инструмент обвинения в вашем контроле версий, он этого достигнет, они просто добавляют шума.
Что еще хуже, они будут привлекать дополнительные комментарии к вашему коду, чтобы сделать его полностью нечитаемым
// added for superEnterpriseyWonder v2.5
string superMappingTag = MakeTag(extras);
if (superMappingTag.empty())
{
// bug fix #12345674 shuld have been true
autoMapping = true;
// bug fix #12345674 should have been true
i++; // v2.6 now need to up the counter DO NOT DELETE
}
// end added for superEnterpriseyWonder v2.5
, а затем кто-то удалит метод, но оставит комментарий к коду в
// added for superEnterpriseyWonder v2.5
// bug fix #12345674 should have been true
// v2.6 now need to up the counter DO NOT DELETE
// end added for superEnterpriseyWonder v2.5
Просто откажитесь от дрянных комментариев
Если вы используете Source Control, я бы рекомендовал добавлять метку сборки в Source Control после каждой сборки. Таким образом, вы можете искать весь исходный текст, измененный для конкретной сборки, без каких-либо неприятных комментариев, забивающих ваш код.
Это из книги Боба Мартина «Чистый код»:
«Правильное использование комментариев - компенсировать нашу неспособность выразить себя в коде. Обратите внимание, что я использовал слово отказ. Я имел в виду это. Комментарии всегда терпит неудачу ».
Я всегда думаю об этой цитате, когда вижу комментарий, чтобы не удивляться, что твоя кровь закипает.
Я бы сказал, что значения нет: эту информацию также можно получить с помощью функции аннотирования / обвинения вашего SCM. Кроме того, любой может добавить текст между этими комментариями, что делает комментарии датированными (поскольку вы можете добавить что-то для v2.6, а в комментариях написано v2.5)
Также следует отметить, что эти комментарии по существу скрыты: только вы видеть их, когда вы просматриваете рассматриваемый исходный код, поэтому вы не можете использовать его для создания журнала изменений или чего-то еще.
Показанный комментарий, вероятно, бесполезен. Однако могут быть случаи, когда добавление функции может вызвать добавление не столь очевидного кода. В этом случае будет уместным комментарий, описывающий изменение и / или почему код не очевиден.
Мало того, что здесь нет значения ... есть отрицательное значение. Ведение комментариев уже в большинстве случаев схематично, это просто добавляет еще одной вещи, с которой люди могут облажаться. Эти комментарии не представляют ценности для читателя и, следовательно, забивают им мозг бесполезной информацией о версии, когда в их памяти может быть еще одна строка кода. Это также еще одна строка, в которой возникает конфликт слияния (здесь я не шучу… Я видел конфликты слияния в комментариях).
Может быть полезно в некоторых случаях (например, если это помогает понять, почему некоторые функции в V3 работают иначе, чем в V2), но в целом задача SCM - знать, что было добавлено когда.
ИМХО Вы не придирчивы. Есть по крайней мере три веские причины не добавлять этот тип комментария в исходный код:
- их место фактически находится в системе управления версиями, где вы можете иметь глобальный обзор всего, что изменилось, чтобы приспособиться к новой версии библиотека или новая функция. При условии, что это сделано правильно и используются журналы.
- если исходный код является частью результатов для клиентов, возможно, им не нужно знать историю того, что произошло. Представьте, что вы внесли изменения для другого клиента и поместили это в комментарии!
- слишком много комментариев не лучше, чем слишком мало.
Строка не ясна, в чем будет разница между
// Compliance with specs abc (additional xyz feature)
...
... // some code
и:
// xyz feature:
...
... // some code
В общем, я бы не стал помещать в исходный код ничего, связанное с историей, но буду комментировать то, что сделано,
Если при виде комментария с избыточным потоком ваше кровяное давление повышается, вам нужно выпить или что-то в этом роде.
Тем не менее, я согласен, что такие комментарии в основном бесполезны. При постоянном использовании программа быстро превратилась бы в лабиринт таких комментариев. Что, если строка была изменена один раз для версии 2.5, а через год снова изменилась для ошибки 3294? Вы помещаете два комментария о версии в одну строку или просто оставляете последнюю версию? Если вы сохраните только самую последнюю версию, то потеряете тот факт, что это было изначально добавлено для версии 2.5. Если вы сохраните их обоих, что произойдет, если произойдет третье изменение или четвертое? Как мы узнаем, в каком состоянии было каждое изменение? Что произойдет, если вы добавите блок кода в версии 2.5, а затем для версии 2.6 вы добавите еще один блок кода, встроенный в блок 2.5? И т. Д. И т. Д. Программа могла легко получить больше комментариев к версиям, чем строк кода.
Если бы не делать последовательно, комментарии быстро вводили бы в заблуждение. Кто-то может добавить комментарий о том, что этот блок был добавлен для версии 2.5, кто-то другой может вставить код внутрь этого блока для версии 2.6 и не комментировать его, и теперь у нас есть комментарий, который, кажется, говорит, что второй блок был добавлен для версии 2.5.
И мы так сильно заботимся? Довольно редко меня волнует, когда было внесено изменение. О, ладно, пару недель назад мне было все равно, потому что я хотел знать, кто виноват в крупном провале.
Как отмечали другие, системы контроля версий делают это за вас в тех редких случаях, когда вам это нужно. Думаю, если бы у вас не было VCS, можно было бы сделать это. Но вы можете получить несколько очень хороших VCS бесплатно. Если он вам нужен, возьмите его. В противном случае вы похожи на людей, которые говорят, что вам следует практиковаться в выполнении арифметических операций в уме, иначе что бы вы сделали, если бы ваш калькулятор перестал работать? Предполагается, что в любой момент все калькуляторы в мире могут одновременно сломаться.
Можно сказать, что это может помочь сказать: «Ооооо, это было добавлено в запись заказа, чтобы поддержать новую табель учета рабочего времени продавца. функция "или что-то в этом роде. Но тогда важно не «Этот код был изменен Бобом для версии 3.2.4», а скорее «Этот код производит эти данные, которые здесь не используются, но необходимы другому модулю там».
I Я твердо сторонник написания комментариев, которые вводят разделы кода и описывают общую идею сложного или иного неочевидного кода. Но это'
Учтите, что некоторым, возможно, придется получить снимки из VCS. В таком случае у них не будет истории, к которой можно было бы прибегнуть ... и такие комментарии станут полезными.
Я видел, что много кода написано людьми, которые до недавнего времени не использовали контроль версий. Думаю, они просто взяли эту привычку, и теперь это трудно остановить.
Еще одна причина, которую я обнаружил, заключалась в том, что иногда важно знать, какой фрагмент кода связан с какой версией. Конечно, вы всегда можете проверить журнал версий, но у вас не всегда на это время, и это раздражает. В некоторых случаях фраза «код для v3.2» больше говорит другим разработчикам, чем «код для выполнения x, y и z» ... все зависит от соглашений, установленных командой.
Другой ответ заключается в том, что в некоторых проекты, с которыми я работал с некоторым кодом, были прокомментированы таким образом, но это было до того, как проект фактически начал использовать контроль версий. В этом случае также имело смысл оставить это так.
Я нахожу их полезными, это позволяет избежать погони за VCS, чтобы выяснить, почему было внесено изменение в код, или чтобы найти идентификатор ошибки для дефекта, если я помню, в чем было изменение кода. .
Хотя теоретически VCS содержит информацию, на практике ее можно похоронить, особенно путем интеграции.
В других работах, что проще:
// DEF43562 - changed default value
foobar = true
Или
- винить (или эквивалент)
- преследовать через истории, чтобы найти правильное изменение.
- Следуйте интеграции до источника и повторите 1 и 2.
- Найдите прикрепленный идентификатор ошибки к первоначальному изменению, если вы lucky.
В основном комментарий - это сокращение от VCS и ненадежной интеграции VCS / BugTracking.
Я считаю, что комментарии также полезны в качестве маркера: «Это решение было рассмотрено клиентами / пользователями / комитет по рассмотрению, и это выбранный ответ, будьте осторожны при изменении поведения ".