Нам необходимо разработать рекомендации по написанию комментариев при регистрации кода в системе контроля версий (например, TFS).Хорошие комментарии к изменениям в sourcecontrol
Е.Г., когда мы подчиняемся устранение ошибки, мы создаем комментарий «исправлена ошибка # ...»
Мы попытались провести мозговой штурм по этой теме, но большинство идей приносят слишком мало добавленную стоимость.
Я был бы признателен за любые предложения по этому вопросу.
Как правило, комментарии, которые мы делаем, когда я работаю, - это краткий обзор изменений, которые были сделаны. Что-то короткое и простое.
Возможно, это не так много, но может быть очень полезно при возвращении в историю, пытаясь найти, когда что-то изменилось (гораздо больше, чем просто «ошибка #####»). Было несколько раз, когда мне нужно было вернуться в историю управления версиями, чтобы попытаться найти, когда изменилось конкретное поведение или фрагмент кода, а краткие обзоры могут значительно облегчить отслеживание там, где это возможно. Если вы просто укажете номер ошибки, вам нужно будет сделать больше работы, чтобы найти эту базовую информацию (вытащить трекер ошибок и найти ошибку).
Если у изменения есть связанный билет где-нибудь или ошибка, в этом случае количество и заголовок (со ссылкой) должны быть достаточными.
В противном случае просто укажите, какие изменения вы внедрили. Регулярные рекомендации для комментариев применяются, вы можете проверить некоторые популярные журналы проекта, чтобы увидеть хорошие примеры.
Я хотел бы включить ссылку на ошибку (билет, вопрос, что когда-либо называли), если это возможно, потому что это обеспечивает контекст и мотивацию для изменения. Кроме того, мне нравится пытаться ответить на вопросы, что изменилось, и почему, как можно ближе к одной строке. Когда я делаю комментарий, я пытаюсь задуматься о своем будущем себе через 6 месяцев, оглядываясь на журналы, разницу и билет, чтобы понять, о чём я думал. Вхождение слишком много деталей никогда не помогает.
Вы можете настроить TFS, чтобы потребовать, чтобы при любой регистрации кода была связана с ним задача TFS.
Команда проекта, которая использует ее там, где я работаю, требует, чтобы все ошибки и/или функции были введены в TFS в качестве задач - и чтобы любая проверка кода была связана с задачами, к которым она относится.
Комментарий также требуется, но у них нет строгих правил для того, что вы пишете, за исключением того, что изменение не требуется для объединения в другую ветку.
Для изменений, которые будут упомянуты в примечаниях к выпуску, включает в себя предлагаемую запись о примечаниях к выпуску либо в комментарии к редактору изменений, либо в связанном отчете об ошибке, если таковой имеется.
Выписывая запись заметки о выпуске, вы вынуждены сделать шаг назад и посмотреть на редактирование с точки зрения пользователя. Это побуждает вас кратко описать, в чем проблема, и как исправление устраняет проблему.
My (а содержательный) руководство вокруг этой темы является «документ почему вы делаете изменения не , что.»
I.e. вы не должны указывать «исправленную ошибку в MyClass.cs и FooBar.cs», потому что этот комментарий не имеет значения - они могут просто посмотреть на набор изменений, чтобы найти эти детали.В равной степени с TFS связывание наборов изменений с рабочими элементами означает, что включение ссылки на рабочий элемент в комментарий является довольно излишним. Вместо этого короткое предложение, объясняющее причину такого изменения, как «фиксированная потенциальная уязвимость XSS в редакторе», является наиболее полезной вещью для чтения при просмотре большой истории изменений.
sentAnce? Давай. –
По возможности (например, при использовании TFS для отслеживания ошибок и управления исходным кодом) свяжите проверок напрямую с соответствующим рабочим элементом. В противном случае добавьте рабочий элемент/ошибку # в комментарии к изменениям. Это минимальный приемлемый уровень комментариев к изменениям.
В комментарии к проверке должно быть указано намерение внесенного изменения, только добавляется подробная информация о том, как изменение приводит к желаемым результатам по мере необходимости. Хорошей отправной точкой было бы название соответствующего рабочего элемента.
Один или два предложения - хорошая цель для комментария. Не будь таким общим, комментарий не имеет смысла (например, «Исправлена ошибка в xyz»), но также не скрывайте намерения изменения под слоями ненужных деталей.
+1 для вставки заголовка проблемы, который должен быть информативным.
+1 для документа, почему, при необходимости в дополнение к заголовку ошибки.
+1 за то, что он сознательно относится к заметкам о выпуске, когда вы хотите сообщить клиентам.
+1 для интеграции SCM, отслеживания ошибок и CI, а также их связи друг с другом по вопросам/ошибкам.
Пожалуйста, сделайте это сообщество wiki, поскольку оно субъективно. – lothar