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

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

// 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, но в основном только в качестве хранилища. Нет веток, нет слияний, ничего, кроме журнала + хранилища.

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

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

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

Похоже, ваша команда не имеет хороших инструментов для вашей системы контроля версий. Поскольку вы сказали, что используете 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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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