Должен ли я изменить имя автора в файле класса, если внесу более 80% изменений?

18

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

Я жадный? или кому-то будет полезно увидеть мое имя и спросить меня в случае сомнений?

Tarun
источник
17
Вы используете контроль версий? Я считаю, что журналы коммитов являются более надежным механизмом отслеживания авторства (если когда-либо есть законная необходимость выяснить это ...)
rwong
5
Имя должно быть там, если оно имеет какое-либо значение для кода. Т.е. контактное лицо. Ответственность и тд. И если такой случай, прикрепите его с указанием даты окончания и нового имени.
Независимо
15
Какова цель иметь имя автора в файлах классов?
BЈовић
2
Если файл имеет заполнитель для имени автора, есть вероятность, что он также содержит заполнитель для журнала изменений. Я бы поставил свое имя в журнале изменений вместо оригинального автора. Во всяком случае, я никогда не оставляю свои отпечатки пальцев на коде, который я пишу, только на отпечатках моего босса.
Mouviciel
1
что плохого в том, чтобы оставить свое имя в качестве автора и добавить строку ниже с надписью «переписанная /
измененная

Ответы:

15

Это действительно зависит ...

Если вы думаете, что есть небольшая вероятность того, что кто-то еще может быть заинтересован позже в том, чтобы спросить оригинального автора, укажите его имя в коде. Если вы думаете, что кто-то может быть заинтересован в том, чтобы спросить вас лично, укажите свое имя. И если вы думаете, что оба могут быть возможны, введите оба имени (или комментарий типа «на основе работы ...»).

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

С другой стороны, у нас есть много макросов VBA, написанных некоторыми парнями, которые были переданы другим парням (некоторые из них покинули компанию за эти годы) и были изменены, все без использования контроля версий. К счастью, комментарии к этим файлам часто содержат имена авторов и некоторый журнал истории.

Док Браун
источник
13

Я только что натолкнулся на другой пост, где OP спрашивал, должно ли имя автора быть даже в заголовке файла, и кажется, что по крайней мере 2/3 ответивших ответили, что имя даже не должно быть в списке, и что вы должны использовать контроль версий для просто следите за тем, кто изменил файл. Не знаю, что случилось с этим постом, но сейчас я не могу его найти. <- (следовательно, анонимное «OP»)

Лично я считаю автора, указанного в заголовке файла, полезным, но по несколько иной причине (и это может не относиться к другим в их среде). Несмотря на то, что мы пытаемся на практике владеть сообществом и часто работаем над различными частями проекта, у нас, как правило, мало членов команды, которые знают определенные области кода гораздо более глубоко, чем другие. Поэтому, когда кто-то (особенно многочисленные подрядчики, которые приходят и уходят) открывают файл, который они никогда не видели прежде, автор становится непосредственным человеком. Он может быть не единственным или даже мажоритарным, но имея свое имя наверху, он признает, что несет определенную ответственность за распространение знаний / информации о коде среди остальной команды. Мы можем перечислить более одного человека в заголовке, если несколько человек действительно внесли свой вклад и чувствуют себя ответственными.

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

Эта практика работает в нашей команде, потому что у нас нет передачи. Если человек не уйдет или не перейдет в другую команду, этот код / ​​проект останется с этим человеком и с нашей командой. Очевидно, что если люди, которые поддерживают код, не совпадают с теми, кто его пишет, то никого не волнует, кто был указан в заголовке.

Итак, в свете моего взгляда на заголовки файлов, я бы сказал, что если вы изменили 80% файла, и вы чувствуете, что теперь у вас есть ответы на любые вопросы (и вы, вероятно, должны чувствовать себя так), да, иди вперед и обновите заголовок файла, чтобы на нем было ваше имя. Если вам не нравится удаление предыдущего человека, вы можете оставить его имя там, по крайней мере, на время. Вы всегда можете спросить оригинального автора, и я уверен, что они не возражают против того, что вы изменили имя, так как я предполагаю, что нет никаких трудностей в том, что вы изменили 80% самого файла.

ОБНОВЛЕНИЕ: нашел этот пост . Понятия не имею, как мне удалось что-то вернуть с августа. Я только что закончил читать «Прагматичный программист», и в последней главе авторы рассказывают о подписании работы и ответственности (в другом посте об этом упоминалось, поэтому я и посмотрел). Книга имеет смысл, и теперь, когда я думаю об этом, возможно, нам следует ввести командную политику, согласно которой тот, кто указан в качестве автора, должен быть включен во все обзоры кода рассматриваемого файла. Не имеет значения, кто изменил файл последним или самым большим в SVN, автор является владельцем и хранителем.

DXM
источник
1
Я вижу ваши очки, но кто такой «ОП»?
Тарун
Это может быть страница проекта или внутренняя вики, где контактная информация может быть размещена на всеобщее обозрение. Сложность помещения этой информации (документации и контактных лиц) в систему контроля версий возникает ... во время ветвления и слияния.
Rwong
@Tarun: OP = "оригинальный постер" (то есть человек, задающий вопрос). Это выражение используется в дискуссионных форумах онлайн.
Слёске
Согласитесь с @Tarun, ссылка на пост поможет в перспективе. Я предполагаю, что это тот ?
Яннис
1
@ rwong: Почему возникает проблема при ветвлении и слиянии? Обычно человек, который объединяет изменения, должен понимать это (иначе, почему они объединяют это?). Таким образом, человек в журнале является тем, чтобы спросить.
Слёске
5

Я не нахожу имя автора ужасно полезным. Как показывает этот вопрос, часто нет единого автора, поэтому назвать «автор» невозможно.

Вы, конечно, могли бы включить список всех людей, которые внесли большой вклад, но вы уже можете получить это из журнала контроля версий - так какой в ​​этом смысл?

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

редактировать

Ответ предполагает проект с использованием контроля версий. Если вы не (последовательно) используете VC, то добавление автора (списка) и, возможно, некоторой истории изменений в файл может быть приемлемым решением. Тем не менее, вы, вероятно, должны начать использовать VC как можно быстрее, в этом случае см. Выше :-).

sleske
источник
so what's the point?Проекты, которые не относятся к vcs, проекты, которые в какой-то момент мигрировали в другой vcs (к сожалению, не все схемы миграции допускают миграцию истории), и проекты, которые используют более одного vcs одновременно - некоторые проекты FLOSS принимают это подход, облегчающий людям вклад, не ограничивая их одним vcs (svn люди находят git трудным, git люди находят svn непригодным, и мы hg люди смеемся над обоими)
yannis
1
@YannisRizos: ОК, это правда. Я неявно предполагал, что любой программный проект будет использовать контроль версий. Отредактировал мой ответ.
Слёске
И, конечно же, мои другие вопросы должны быть легко решены с помощью небольшого vcs-fu, независимо от задействованных vcs. Но на практике они редко бывают, к сожалению.
Яннис
2

Если файл был значительно изменен, допустимо добавить ваше имя в файл, как кто-то, кто что-то знает об этом.

Пол Натан
источник
1

Создатель исходного файла должен / должен всегда (ИМХО) указываться в исходном файле. Это, с хорошим заголовком, должно показать, почему автор разработал исходный код и что он / она думает о написании кода. Что касается сопровождающего кода, добавление имени сопровождающего имеет решающее значение для отслеживания контроля версий.

Именование автора, опять же, ИМХО, должно включать исходную версию кода вне системы контроля версий, первую дату, когда произошло изменение, а также номер запроса на изменение. Причина в том, что если решение об изменении VCS возникает, существует история версии кода, кем был автор, а также номер запроса на изменение, на который могут ссылаться разработчики (если им нужно знать, почему сопровождающий сделал то, что он / он она сделала). Таким образом, в нашей организации наш формат выглядит следующим образом:

/**
 * $comment
 * <p />
 * $cr_number, $date, $author, $description 
 **/
Бухаке синди
источник
3
«Если решение об изменении VCS возникает, есть история версии кода». Я надеюсь, что ни одна здравомыслящая организация даже не рассмотрела бы миграцию VCS без миграции истории (по крайней мере, недавней истории). Это, в конце концов, смысл использования VCS.
Слёске
1
Полностью не согласен. Такая информация должна отслеживаться с помощью контроля версий. В противном случае действительно невозможно узнать, кто внес изменения в какие строки (при условии, что над файлом работало более одного человека). Поместить его в файл - это просто дубликат информации, доступной в другом месте.
Брайан Оукли
1
@Bryan Oakley, я вообще не убираю контроль версий, я утверждаю, что распознавание кода в коде - это способ узнать, кто работал с исходным кодом, без необходимости выполнять необходимый поиск через контроль версий. Кроме того, есть некоторые коды, которые доступны за пределами систем контроля версий, следует ли исключить имя автора?
Бухаке Синди
1

Мне нравится видеть оригинальное имя автора, хотя бы для того, чтобы найти кого-то, кто начал бы мои поиски ответов о коде. (У автора обычно нет воспоминаний, но это по крайней мере выстрел!)

Я бы порекомендовал вам просто добавить свое имя ниже оригинального автора.

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

ka9cql
источник
+1 за третий абзац, поскольку первоначальный автор может знать другого человека, который что-то сделал в коде, но не указал его имя.
Coyote21
1

Моя политика в отношении комментариев @author:

  1. Если это новый файл, я ставлю себя как @author.
  2. Если это существующий файл, я оставляю @author в покое, независимо от того, что я делаю с файлом.

Если у вас есть вопросы по поводу чего-либо, не имеет значения, кто @author файла - важно, кто @author какой части файла вы редактируете. Вот для чего [git/svn/whatever] blame.

ИМО, @author нужно уйти.

Майкл Мусса
источник
С одной стороны, вы указываете себя в качестве автора в новом файле. С другой стороны, вы хотите, чтобы автор ушел?
Энтони Пеграм
1
Стандарты кодирования компании требуют наличия тега @author. В противном случае я бы не использовал его вообще (потому что я хочу, чтобы это ушло :)).
Майкл Муса