19

I am refactoring existing set of java test classes for automated UI tests. At times I end up in making massive changes in class file or completely revamping it. This makes me think that when I am rewriting entire class then should I change author name in comment section to mine?

Am I being greedy? or is it going to be useful for one to see my name and ask me in case of doubts?

Improve this question
6
  • 17
    Are you using version control? I find commit logs to be a more reliable tracking mechanism for authorship (if there's ever a legitimate need to find out...)
    – rwong
    Dec 21, 2011 at 6:36
  • 5
    The name should be there if it have any kind of value to the code. I.e. contact person. Responsibility and so on. And if such case, stick it with a end date and new name attached.
    – Independent
    Dec 21, 2011 at 7:32
  • 15
    What is the purpose of having an autor's name in class files?
    – BЈовић
    Dec 21, 2011 at 8:22
  • 2
    If the file has a placeholder for an author name, chances are that it has also a placeholder for change log. I would put my name in change log instead of original author. Anyway, I never leave my own fingerprints on code I write, only those of my boss.
    – mouviciel
    Dec 21, 2011 at 8:56
  • 1
    what is wrong with leaving their name as author and adding a line below that says "rewritten/refactored name date"
    – Ryathal
    Dec 21, 2011 at 14:01

7 Answers 7

Reset to default
15

It really depends ...

If you think there is a slight chance that someone else might be interested later in asking the original author, let his name in the code. If you think someone might be interested in asking you in person, let your name in it. And if you think, both might be possible, let both names in (or a comment like "based on the work of ...).

Of course, when the use of source control is mandatory in your workplace, and that is the only way of getting access to the sources, then save the hussle and strip every author comment out of the source. In my workplace, for example, we have lots of source files in source control where we don't bother to write any names into the sources. If I want to know who is responsible for the file, or was in the past, or for a specific change, TortoiseSVN will easily produce me a log for that.

On the other hand, we have a lot of VBA macros, written by some guys, passed around to other guys (some of them left the company over the years) and were modified a lot, all without using source control. Luckily, comments of those files contain often author names and some kind of history log.

Improve this answer
13

I just came across another post where OP was asking if author's name should even be in the file header and seems that at least 2/3rd of people who responded said that the name shouldn't even be listed and that you should use version control to simply keep track of who changed the file. Don't know what happened to that post, but now I can't find it. <-- (hence anonymous "OP")

Personally, I find author listed in the file header to be useful but for a slightly different reason (and this may not relate to others in their environments). Even though we try to practice community ownership and often work on various parts of the project, we tend to have few team members who know certain areas of the code much more intimately than others. So when someone (especially numerous contractors that come and go) open a file that they've never seen before, author becomes the go-to person. He may not be the only contributor, or even majority contributor, but having his name at the top, he acknowledges to have certain responsibility in distributing knowledge/information about the code to the rest of the team. We can list more than one person in the header is multiple people have indeed contributed and feel responsible.

I do find it frustrating when I have a question about a file and have to resort to version control to identify primary, or most knowledgeable person. Then end up going from one guy to the next as they all deny really knowing what the code does... they just had to go in and fix a bug or two.

This practice works in our team because we don't have hand-offs. Unless a person quits, or moves to a different team, that code/project will stay with the person and with our team. Obviously if people who maintain the code are not the same as those that write it, then nobody would care who was listed in the header.

So in light of my view on file headers, I'd say if you changed 80% of the file and you feel like now you are the go-to guy for any questions (and you probably should feel that way), yes, go ahead and update the file header to have your name on it. If you feel bad about removing previous person, you could leave their name there as well, at least for the time being. You can always ask original author and I'm sure they won't mind one bit that you changed the name, since I'm assuming there's no hard feeling about you changing 80% of the file itself.

UPDATE: Found that post. Have no idea how I managed to pull something back from August. I just finished reading The Pragmatic Programmer and in the last chapter authors talk about signing work and accountability (the other post mentioned it, that's why I looked it up). The book makes perfect sense and now that I think about it, maybe we should introduce team policy that whoever is listed as the author, should be included in all code reviews of the file in question. Doesn't matter who changed the file last or most in SVN, the author is the owner and is the keeper.

Improve this answer
7
  • 1
    I see your points but who is "OP"?
    – Tarun
    Dec 21, 2011 at 7:08
  • There could be a project page, or an internal wiki where contact information can be put up for everyone to see. The difficulty with putting those information (documentation and contact persons) into source control arises ... during branching and merging.
    – rwong
    Dec 21, 2011 at 7:09
  • @Tarun: OP="original poster" (i.e. the person asking the question). It's an expression used in online discussion forums.
    – sleske
    Dec 21, 2011 at 7:46
  • Agree with @Tarun, a link to the post would help put your answer in perspective. I'm guessing it's this one?
    – yannis
    Dec 21, 2011 at 7:47
  • 1
    @rwong: Why is there a problem during branching & merging? Normally the person who merges a change should understand it (otherwise, why are they mergin it?). So the person in the log is the one to ask.
    – sleske
    Dec 21, 2011 at 7:48
5

I don't find the name of the author terribly useful. As this question shows, often there is no single author, so naming "the author" is not possible.

You could of course include a list of all people who made major contributions, but you can already get that from the revision control log - so what's the point?

On my project, there is no author info in most files. If you have a question, you just look into the logs, and usually it's obvious that one or two people did most of the work, so you ask them.

Edit

The answer assumes a project using version control. If you do not (consistenly) use VC, then putting an author (list), and maybe some change history into a file might be a viable workaround. Still, you should probably start using VC as quickly as possible, in which case see above :-).

Improve this answer
3
  • so what's the point? Projects that aren't under a vcs, projects that at some point migrated to a different vcs (not all migrations schemes allow for history migration, unfortunately), and projects that use more than one vcs at the same time - some FLOSS projects adopt that approach to make it easier for people to contribute, without limiting them to one vcs (svn people find git hard, git people find svn unusable, and we hg people laugh at both)
    – yannis
    Dec 21, 2011 at 7:55
  • 1
    @YannisRizos: OK, that's true. I implicitly assumed any software project would use version control. Edited my answer.
    – sleske
    Dec 21, 2011 at 8:04
  • And of course my other points should be easily solved with some minor vcs-fu, regardless of the vcs involved. But in practice they rarely are, unfortunately.
    – yannis
    Dec 21, 2011 at 8:10
2

If the file's been modified significantly, it should be acceptable to add your name in the file as someone who knows something about it.

Improve this answer
1

The creator of the source file should/must always (IMHO) be mentioned in the source file. This, with good header commenting, should show why the author developed the source and what his/her thinking was for writing the code. As for the maintainer of the code, adding the name of the maintainer is crucial for source control tracking.

The naming of author, IMHO again, should include source version of the code, outside of the version control system, the first date of when the change occurred, as well as the change request number. The reason is, if the decision to change VCS arises, there's history of the version of the code, who the author was as well as the change request number that developers can refer to (if they need to know why the maintainer did what he/she did). Thus, in our organisation, our format is as follows:

/**
 * $comment
 * <p />
 * $cr_number, $date, $author, $description 
 **/
Improve this answer
3
  • 3
    "if the decision to change VCS arises, there's history of the version of the code" I hope no sane organization would even consider migrating VCS without migrating history (at least recent history). That, after all, is the point of using VCS.
    – sleske
    Dec 21, 2011 at 7:53
  • 1
    Completey disagree. That sort of information should be tracked with version control. Otherwise there is really no way to know who made changes to what lines (assuming more than one person has worked on a file). Putting it in the file is simply a low fidelity duplicate of information available elsewhere.
    – Bryan Oakley
    Dec 21, 2011 at 14:10
  • 1
    @Bryan Oakley, I'm not removing version control at all, I'm stating that recognising one's in code is a way of knowing who worked on the source, without needing to do necessary lookup via version control. Besides, there are some codes that are available outside of version control systems, should the author name be excluded?
    – Buhake Sindi
    Dec 21, 2011 at 14:38
1

I like seeing the original author's name, if only to find someone to start my quest for answers about the code. (The author commonly has no recollection, but it's at least a shot!)

I would recommend that you simply add your name below the original author's.

There is no need to replace the other person's name, as they may know some aspect of the original business need that you don't, and others following after you might need to talk to that person as well.

Improve this answer
1
  • +1 for the third paragraph, since the original author might know some other person who has done something in the code, but have not put his name on it.
    – Coyote21
    Dec 27, 2011 at 15:41
1

My policy on @author comments is:

  1. If it's a brand new file, I put myself as the @author.
  2. If it's an existing file, I leave @author alone, regardless of what I do to the file.

If you have questions on something, it doesn't matter who the @author of the file is - it matters who the @author of what portion of the file you're editing is. That's what [git/svn/whatever] blame is for.

IMO, @author needs to go away.

Improve this answer
2
  • On the one hand, you list yourself as the author in a new file. On the other hand, you want the author to go away?
    – Anthony Pegram
    Dec 23, 2011 at 18:53
  • 1
    Company coding standards require the presence of the @author tag. Otherwise, I wouldn't use it at all (because I want it to go away :)).
    – Michael Moussa
    Dec 23, 2011 at 21:48

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.