Есть ли смысл включать «журнал изменений» в каждый файл кода, когда вы используете контроль версий?

75

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

// 2011-06-14 (John Smith) Change XYZ to ABC to fix Bug #999

а также:

// 2009-95-12 (Bob Jones) Extracted this code to Class Foo 
// <commented-out code here>

Причина этого, как мне объяснили, заключается в том, что слишком долго просеивается журнал VCS, пытаясь выяснить, кто что изменил и почему, имея это в самом файле кода, либо вверху, либо рядом с соответствующим. изменить, позволяет легко увидеть, кто изменил что и когда. Хотя я вижу в этом смысл, это кажется излишним и просто отчасти похоже на «Э, мы действительно не понимаем, как правильно использовать нашу VCS, поэтому мы вообще не будем беспокоиться об этом».

Как вы думаете? Используете ли вы комментарии и журнал? Просто журнал? Считаете ли вы, что проще кодировать, когда вы видите над блоком кода, что Джон Смит изменил метод проверки XYZ неделю назад вместо того, чтобы искать в журналах и сравнивать файлы кода в инструменте Diff?

РЕДАКТИРОВАТЬ: Использование SVN, но в основном только в качестве хранилища. Нет веток, нет слияний, ничего, кроме журнала + хранилища.

Уэйн Молина
источник
4
Какую систему контроля версий вы используете?
ChrisF
11
Некоторые магазины использовали журналы изменений до появления систем контроля версий. Инерция и фамильярность хранят журналы изменений.
Гилберт Ле Блан
2
+1 - Моя команда также делает это, и я пытался убедить некоторых из них, что это роль VCS. Проблемы начинаются, когда эти комментарии не обновляются с актуальным кодом ... И хуже всего то, что руководство решило добавить журналы изменений и в каждый метод.
безрассудно
2
+1 - Я боролся с нашим старшим разработчиком почти два года по этому поводу. Его единственное обоснование для добавления этих бесполезных комментариев заключается в том, что это несколько облегчает объединение изменений в 3000-строчные методы. Мысль о том, что метод из 3000 строк является непристойным, встречается с презрением.
Джошуа Смит
1
Если «просеивание [ваших] журналов VCS» занимает слишком много времени, вы делаете что-то не так.
Кит Томпсон

Ответы:

46

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

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

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

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

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

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

/// The GaidenCommand is a specialized Command for use by the
/// CommandManager.
///
/// Note, the word "gaiden" is Japanese and means "side story",
/// see "http://en.wikipedia.org/wiki/Gaiden".
/// Why did I call this "GaidenCommand"? Because it's very similar to
/// a regular Command, but it serves the CommandManager in a different
/// way, and it is not the same as a regular "Command". Also
/// "CommandManagerCommand" is far too long to write. I also toyed with
/// calling this the "AlephCommand", Aleph being a silent Hebrew
/// letter, but Gaiden sounded better.

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

Джордж Стокер
источник
4
Всякий раз, когда я борюсь с определенным фрагментом сложной логики, комментарии иногда могут помочь мне понять, почему логика столь же запутана, как и она. Но в целом я с тобой согласен.
maple_shaft
5
У каждого разработчика есть по крайней мере несколько плохих качеств, я знаю, что не должен, но я просто не могу остановиться :) Каждый раз, когда я пишу TODOкомментарий, умирает щенок.
maple_shaft
32
Удаление комментариев других людей с предубеждением в некотором смысле навязывает ваш собственный стиль программирования и веру в других. Младшие и пацифистские программисты не будут лаять, но время от времени вы сталкиваетесь с альфа-самцом, и тогда начинается бой, которого не должно было быть. Итак, вы прочитали в умном блоге умного человека, что когда дело доходит до комментариев, меньше значит больше. Другие, возможно, не читали ту же книгу. Даже если вы считаете, что правы, потому что несколько человек на SO с 5k + rep соглашаются, диктатура не является способом совместной работы. Я работал под альфа-самцом и ушел.
Работа
8
@ Нил Баттерворт: re: ructions: Код должен быть податливым. Рефакторинг, изменение, улучшение. Это предназначено для этого. Это не должно быть написано только один раз. Наше понимание бизнеса меняется, и когда это происходит, нам нужно изменить код. У меня много проблем с комментариями, но самое важное для нашего обсуждения - это то, что комментарии редко синхронизируются с кодом, и, как правило, они не объясняют, почему что-то происходит. Когда это происходит, его легко удалить. Если кто-то приходит ко мне и спрашивает, почему я удалил следующий комментарий file.Open() // Open the file. Я бы посмеялся
Джордж Стокер
5
Несколько дней назад я написал фрагмент кода, очень сложные математические вычисления, полные тригонометрии, преобразований, чего угодно ... Мне понадобилось около полутора часов, чтобы написать менее 10 строк кода. Практически никто вокруг меня не понимает, как это работает. Я не пойму это и через несколько недель. С другой стороны, почему это там тривиально. Итак, над этими несколькими строчками находится целая глава текста, объясняющая что, а не почему. Если бы вы пришли и удалили этот комментарий, я бы ударил вас по лицу, винт уволили.
Давор Адрало
76

Эти «журналы изменений», внедренные в код, особенно наивные. Они просто проявляются как еще одно различие, когда вы вносите изменения, и вас это действительно не волнует. Доверяйте своей VCS - у большинства есть функция "обвинения", которая очень быстро покажет вам, кто что изменил.

Конечно, по-настоящему ужасной была та особенность «старых» VCS, где вы могли встроить фактический журнал VCS в исходные файлы. Сделано слияние практически невозможно.

Нил Баттерворт
источник
14
Мало того, что они проявляются как еще одно отличие, еще хуже, они также могут со временем ошибаться , тогда как любой хороший VCS всегда сможет рассказать вам, кто действительно написал конкретную строку, а также историю вокруг этой строки. Единственное, что хуже бесполезных комментариев - это вредные комментарии. Эти комментарии начинаются как бесполезные и в конечном итоге становятся вредными, если не полностью игнорируются.
Бен Хокинг,
10

У меня есть один файл ChangeLog для каждого проекта, который автоматически заполняется определенными сообщениями коммита.

У нас нет встроенных комментариев ChangeLog. Если бы мы это сделали, я бы удалил их и «поговорил» с человеком, который их добавил. Я думаю, что они указывают на то, что вы не понимаете инструменты, которые вы используете, особенно VCS.

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

dietbuddha
источник
8

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

Но что я знаю ...

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

С другой стороны, мой магазин в основном занимается C #, и мы всегда используем встроенные XML-комментарии для документирования нашего API, поэтому чтение документации об изменениях в открытом API-интерфейсе более или менее просто, чем использование intellisense.

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

Джон Коннелли
источник
6

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

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

Tangurena
источник
5

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

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

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

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

Tyanna
источник
5

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

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

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

wolfgangsz
источник
4

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

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

DaveE
источник
1
+1 Я собирался написать этот ответ, но вы избавили меня от неприятностей. В качестве источника распространяются не только хранимые процедуры, но и многие языки сценариев. Я часто использую OpenACS и TCL - часто, если у клиента есть разветвленная версия определенного файла, единственный способ ГАРАНТИРОВАТЬ, что вы знаете, какая у них версия, это читать журнал изменений. Особенно удобно, если вы вошли на сайт клиента и не можете легко выполнить сравнения с программным обеспечением для контроля версий.
TrojanName
3

Если вы используете SVN, это бесполезная трата времени.

SVN имеет функцию вины. Это скажет вам точно, кто сделал каждую строку в данном файле и когда.

как зовут
источник
1

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

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

При этом комментарии к журналу изменений в коде должны быть относительно редкими. Я не рекомендую добавлять комментарии к журналу изменений каждый раз, когда происходит изменение кода, или когда исправлена ​​настоящая ошибка. Но если исходным требованием было «Foo является необязательным», и кто-то пришел и изменил требование на «Foo требуется для поддержки нижестоящей панели процессов», это то, к чему я настоятельно рекомендовал бы добавить комментарий. Потому что существует большая вероятность того, что какой-то будущий пользователь / аналитик не будет знать о нижестоящем процессе Bar и не будет знать причину, по которой Foo был необходим, и попросит снова сделать Foo необязательным и вызвать головные боли в процессе Bar.

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

Джастин Кейв
источник
Существуют ли какие-либо преобразования VCS, которые не сохраняют сообщения фиксации?
Дэвид Торнли
1
@ Дэвид - я видел много чего не сделал. Я не знаю, были ли технические препятствия для этого или кто-то решил, что было бы проще просто «начать все заново» и проверить весь код новой VCS в первый день.
Джастин Кейв,
добавление комментария, объясняющего, почему процесс изменился, может быть полезным, и иногда добавление комментария, объясняющего, когда он изменился, но я не вижу смысла помещать этот комментарий в виде журнала изменений. Во-первых, это несколько скрывает полезность комментария («О, это просто комментарий в журнале изменений»), и, во-вторых, он поощряет дальнейшие ненужные комментарии в журнале изменений (подчеркивая № 1).
Бен Хокинг
Выйти из визуального источника безопасно? Все полезные современные системы контроля версий правильно обрабатывают журналы изменений. Мы знаем это по определению, потому что если бы они этого не сделали, они не были бы признаны полезными. Потратьте 30 минут на изучение использования управления исходным кодом, которое у вас есть, это сделает вас намного эффективнее, чем просто молитва тому, кто знает, что ваши инструменты избавят вас от крошек. Не говоря уже о том, что довольно часто история кода не имеет значения, сейчас вы только тестируете и пишете.
ebyrob
Что касается «изменения управления исходным кодом» - почти все современные системы могут перемещать историю одну в другую, выводить отдельные файлы изменений уровня проекта или с небольшими усилиями фактически вставлять свои журналы изменений в исходный файл (когда это становится уместным на ходу). не раньше, чем). Таким образом, технология есть, и люди, решившие не использовать контроль источника, являются проблемой.
ebyrob
1

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

Сверре Раббелье
источник
1
какие лицензии говорят это?
Trasplazio Garzuglio
2
Я работал в месте, где соблюдение Сарбейнса-Оксли, которое, как они верили, требовало изменения блоков в исходных файлах. Они также использовали PVCS («Измерения») в течение многих лет, поэтому у них действительно не было никакого контроля версий, но что я знал?
Брюс Эдигер
@ Марко: я не помню, или я бы связался с этим.
Сверре Раббелье
1
Раздел 2a GPLv2 требует этого. Большинство проектов игнорируют это, у некоторых есть единственный файл "ChangeLog" (часто генерируемый из их VCS).
DSAS
0

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

briddums
источник
1
Лично мне немного неприятно, когда 200-строчный файл становится длиной 1000 строк из-за добавления журнала изменений в каждый исходный файл. Этот дополнительный шум фактически затеняет то, что важно совсем скоро.
ebyrob