Для комментариев контроля версий, что другие пользователи рекомендуют - прошедшее или настоящее время?
Т.е.
- Изменено х на у.
- или
- Меняем x на y.
comments
source-code
Роберт У
источник
источник
Ответы:
Комментарии следует читать в контексте, поэтому:
настоящее время
Для исходных комментариев выше метода или до появления какого-либо поведения:
прошлое
Для комментариев источника после некоторого поведения произошло
И для фиксации сообщений
Смешанный пример:
источник
Прошлое - Поскольку любой, кто читает его в будущем, будет ссылаться на акт изменения, который произошел в прошлом.
Формулировка чего-либо как «Изменение» подразумевает, что вы в настоящее время вносите изменения и что код может быть не завершен.
примечание: лично я добавляю комментарии к изменениям только тогда, когда произошли радикальные изменения.
источник
Комментарии - это статичные вещи, поэтому они должны представлять состояние программы как есть , а не так, как оно будет. Чтобы ответить на ваш конкретный вопрос, было бы более уместно использовать прошедшее время .
Тем не менее, этот тип комментариев лучше подходит для вашей системы контроля версий. Контроль версий намного лучше выполняет отслеживание изменений, чем ручные комментарии. В системах контроля версий более уместно документировать в настоящем времени, поскольку эти комментарии применяются в момент принятия изменения. Но, либо будет работать.
Я настоятельно рекомендую, чтобы единственными комментариями в вашем коде были то, что требуется для понимания самого кода - цель, бизнес-логика и исключительные случаи. Оставьте документацию об изменениях в вашей системе контроля версий. Если вы не используете VCS, начните прямо сейчас. Существует несколько бесплатных высококачественных VCS (Subversion, Mercurial, Git и т. Д.).
источник
Я использую императив настоящего времени, так что-то вроде:
Это рекомендуется разработчиками Git:
Поначалу это может показаться немного странным, но если вы думаете о коммите как о патче, который что-то делает, он имеет больше смысла. (Это особенно верно для DVCS, такого как Git, где вы извлекаете наборы изменений у других людей, которые действуют в вашем репо.)
источник
Это не имеет значения; Я думаю, что это личный стиль и предпочтения. Что касается написания почти всего, просто будьте последовательны с собой и с другими комментариями.
источник
Комментарии к коду должны быть естественными для чтения.
Если вы читаете код , говорите себе «Этот код будет делать X» , то вы должны написать комментарий в настоящее время , как это, вероятно , как кто - то читает код в то время будет думать , как хорошо. Если, с другой стороны, вы в какой-то момент думали: «Этот код сделал X», то это должно быть в прошедшем времени. В конце концов, все сводится к личным предпочтениям, если только по какой-то причине у вас нет указаний о том, как комментировать ваш код (например, для командного проекта или для класса и т. Д.).
источник
Если вы используете git, соглашение состоит в том, чтобы использовать настоящее время, потому что сообщения коммитов, сгенерированные с помощью инструментов git (например, слияние), используют настоящее время.
источник
Вы должны использовать прошедшее время.
Причина в том, что вы отвечаете на вопрос, чего достиг этот коммит? Думайте об этом, как о том, что вы рассказываете своей VCS:
Чтобы привести контрпримеры, использование будущего времени звучит так, будто вы просите кого-то сделать это:
и использование настоящего времени звучит так, будто вы на полпути:
источник
Используйте настоящее время: «Измените X на Y», почти как если бы это был элемент в чистом списке TODO.
В общем, как в сценарии, избегайте глаголов типа «быть» и «есть». Например, это не «он ходит», а «он ходит».
Но в этом конкретном примере - если вы говорите о комментариях к коду, а не о комментариях регистрации - я считаю, что «Изменить X на Y» - ужасный комментарий. Он не добавляет никакой новой информации, и если код будет изменен, он может быть даже неверным. Лучше, если вы извлечете код в метод (или класс), а затем документируете этот метод. Если это достаточно ясно, тогда достаточно хорошего имени метода.
Говоря о том, что для документирования методов вы могли бы использовать будущее время, например: «Если предоставленное число является отрицательным,
abs
вернет величину числа».источник
Комментарии являются (или должны быть), как и все написанные, выражениями чего-либо, и они должны просто следовать тем же правилам на естественных языках (принимая во внимание сокращения и сокращения, характерные для задокументированной ситуации или артефакта).
Комментарии к настоящему времени ( .ie «он меняется» или «он меняется» ) указывает на то, что часть данных, управляемая задокументированным алгоритмом, каким-то образом подвергается воздействию. Таким образом, это указывает, что код делает или что происходит с данными, которыми манипулируют.
Комментарии в прошедшем времени должны указывать на утверждение, предварительное условие или постусловие того, что произошло до того момента, когда находится комментарий. Например:
Ввод уже был проверен перед вводом этого блока кода
или
Данные были записаны в файл в конце исполняемого кода.
Комментарии в прошедшем времени также могут объяснить, почему что-то делается ( эта функция выполняет X и Y для решения проблемы с устаревшей базой данных ).
Комментарии в прошедшем времени, указывающие на изменение самого кода (.ie. X был изменен на Y ), не должны существовать в коде. Вместо этого они должны существовать как комментарии к редакции в репозитории исходного кода.
Комментарии в будущем должны указывать на условие, которое должно быть выполнено или выполнено, но по X или Y причине не выполняется сейчас. Например:
Когда мы, наконец, мигрируем БД, нам придется изменить эту логику
или
TODO: как можно скорее, еще раз проверьте правильность ввода - это может не сработать для ввода типа X или Y, может потребовать значительных изменений, которые не могут быть реализованы прямо сейчас.
Для более поздних комментариев типа TODO должна существовать некоторая другая форма документации, чтобы убедиться, что такие изменения действительно имеют место. Последнее, что вы хотите, это TODO, потерянные во времени и пространстве: P
Возьмите это с крошкой соли, но, как правило, это те правила, которым я обычно следую, когда делаю свои собственные комментарии.
источник
Комментирование - это общение с людьми, поэтому, хотя важна последовательность, важно не увязать в принципах, когда сами принципы мешают хорошему общению. Тем не менее, я использую следующие псевдостандарты:
Комментарии, описывающие желаемое поведение, принимают форму императивного предложения настоящего времени.
Используйте набор ключевых слов из всех заглавных букв для описания общих тем в коде (и для упрощения поиска):
источник