Do you sign each of your source files with your name? [duplicate]

Question

Possible Duplicate:
How do you keep track of the authors of code?

One of my colleagues is in the habit of putting his name and email address in the head of each source file he works on, as author metadata. I am not; I prefer to rely on source control to tell me who I should be speaking to about a given set of functionality.

Should I also be signing files I work on for any other reasons? Do you? If so, why?

To be clear, this is in addition to whatever metadata for copyright and licensing information is included, and applies to both open sourced and proprietary code.

Answer 1

Not really, no. There are a couple of reasons why:

• Your version control system (VCS) stores this metadata already. E.g. each commit in git has a field for the name who made the commit. Competent version control systems allow you to see who made a change on a specific lines of code as well. That functionality is usually called blame which is a misnomer as, instead of finding someone to do actual blaming on, it is most useful for finding someone to talk with about a problem you have in the context of the piece of code).

  I've seen some header comments that have history log as well, but that can easily be extracted from a VCS as well.

• It discourages code collaboration. "Hey, someone made this... maybe we shouldn't touch his code". If there is no sole code ownership on some source code file then the higher chance that someone else will change it, which in turn facilitates and enables refactoring.

What about copyright notices?

Though for the sake of copyright you might want to add the company's name as the copyright holder in the header comments (aka copyright banner). If it's an open source project then it is often the name of the maintainer organization or just one maintainer instead. However it is now common practice to put this information in text files at the root of the project. You can see these text files done on open source projects with names such as README, LICENSE, and/or CONTRIBUTORS.

What about database scripts?

You could argue you need to do history logs in header comments with database SQL scripts though lately with database migration tools has made this an obsolete practice. Database migration tools usually keep track of which migrations were run and can do rollbacks as needed. These tools are more flexible to use than a text file.

Answer 2

I don't do this, specifically as you said because it is tracked in source control. Any time information like this is kept in two places (source control, and the file itself as you said), they will become out of synch. Since source control automatically adds the information, I don't think there's any reason to include it directly.

That being said, if there's something that's non-obvious that you're adding, or may warrant further discussion, I think it's worthwhile adding comments around a block of code indicating the change made and why with your name.

Answer 3

Yes, I sign my code. I take pride in producing quality work.

Answer 4

Should I also be signing files I work on for any other reasons? Do you? If so, why?

There is a reason for putting your name in your files. The book "The Pragmatic Programmer" encourages it, because the authors assume that you'll write better code when your name is written on it, so you can take pride in your work. Programmers wouldn't want to sign messy pieces of code, would they?

Well, here's where reality strikes. Most of the times, only the initial author is in the files and like others here stated, this information will be out of synch soon. And it does not prevent messy code. Most just ignore the fact that their name is listed in the file's header. This isn't a very pragmatic advice at all, from an otherwise excellent book, although to some people it may make a difference.

Another reason for keeping your name in the files is when you want to publish source code, for example for an open source project. This can be seen as some sort of advertisement.

But in most cases, this information is merely redundant noise.

Answer 5

git blame (or svn blame if you must) is a much better tool for deducing code "ownership" than a one-liner at the top of a file, especially after a project has grown a few whiskers.

Answer 6

Why would you want a comment with someone's name in it in your source code?

If offers no insight in to the intent of the code and unless you struggle to remember your own name has no value at all that I can see.

It would be removed at the next commit if I came across it.

Of course, comments are generally a smell in themselves but that's another topic:)

Answer 7

No, I don't. However, any mandated headers (a particular company-standard header comment is part of the coding style guidelines) are included, so if they require this as part of them, then I would. If you don't have project, program, or corporate coding styles, then you should, and any mandated file header comments should be clearly defined.

Like you said, version control should be managing this. When other people touch the file, are they supposed to update a field that's already automatically tracked by version control, which identifies exactly what was changed and who made the change between every version? That just seems like overhead, especially if a developer forgets to update that and future developers go by the header rather than looking in version control.

Answer 8

I do. The reason is not because I want to "own" it somehow, by putting my name on it. If someone wanted to edit that line out, I could care less. And saying version control will store my data is true, and yet pointless if someone doesn't have access to my repo.

I work for a big corporation, and my code wanders from business unit to business unit. The poor schmuck who gets the code from a guy, who got it from another guy, who got it from my idiot boss, isn't going to have the faintest clue who to call for support unless I leave a hint in the code itself.

And, because I don't expect to stay here forever, I leave real contact information, so people can contact me after I've left my current job if they need something. It's just courtesy.

Answer 9

My IDE automatically puts usernames at the top of files when you create a new class. It's kind of annoying actually, because we just ignore that header.

hm, maybe we should institute a new coding standard where everyone has to turn that off in the preferences of their IDE and/or delete the automatic header...

Answer 10

In my company, we use a standardized header with a copyright note for our company name, and keyfields for the version control, like Revision, Date, Id

Answer 11

It is standard for us to put our name in the source code and additionally, if we modify it, to mark those changes with a change number and our name against that change number.

TBH, this is the sort of thing that I would have expected to see in in-house coding standards.

Answer 12

I think it's not so bad a habit.

Others argue, that VCS will do that for you. Well, up to a certain point, that is true.

If however you release code under a weak copyleft (MIT or whatever), you can almost bet, that somebody will integrate a snapshot of your code into their code base and will make his own modifications. They will not be able to tell the difference between original comments and the comments of the person, who made the original check-in.

Same thing applies when code bases move to other VCSs (for example from CVS to git). You can't really tell whether all that metadata will make it into the new VCS (I would expect there is some way to migrate it).

So to answer the question:

When it adds significant value to know the author of a piece of code (which is not always the case), than adding the author right into the source file is a good idea. That doesn't mean that you should document and sign every single change you make to a source file.

Answer 13

I'm sure I will get negative points here.

I place my name in files I have created. I also include the company name and address, a copyright statement, a description of the purpose of the file, the original NAME of the file (in the file), and a brief history of major revisions.

Why do I do this:

1. Company name, address and copyright statement makes it very easy to produce in court, should that ever be needed, and show date / time of creation, ownership, etc for the purpose of copyright. Without that information IN THE FILE you are relying on smoke and mirrors to convince a judge who knows nothing about software or VCS.

2. Putting the original author name in at the time of creation is about accountability. If your VCS gives the same info, thats nice but it is not in your face. If the thing is changed later and someone adds bugs, the VCS tells the story. If you are proud of your work, don't hide. [A number of commercial companies require this kind of thing for plain accountability reasons as well.]

3. I put the name of the file in the file because these things change. It is a pain to update this when the name changes, and I'm no longer sure of the value. However, it helps put the whole picture together when looking at source.

4. Every file has a summary in a para or 2 of its purpose. If a file of source has no purpose, don't create it. If it has a purpose, tell me what that is - DO NOT MAKE ME GUESS. About 95% of all the open source code I comes across does not have a purpose stated in the source files and this drives me nuts. I don't want to guess the purpose from the file name or content, for crying out aloud - tell me. Not putting in a purpose is simply LAZINESS. (And not updating the purpose is also laziness.)

5. Pre VCS I used to put a full history in the comments at the start. Post VCS I did this for a while too. It shows history in the file w/o having to go digging anywhere else. It is however a pain so do this, and low value. Use your VCS history for this. But in the headers if you make a major change (huge refactoring, re-purposing, etc) - then make a note for the benefit of others. (And like the original author, put in your name.) It is of course a judgement call as to what is major and what is not. But this is a courtesy to those who come after you.

I also have extensive comments in the file which set out what things do - comments for example on interfaces, APIs, headers, are essential for a user of your API or function or method to know what is going on, and especially any special notes or side effects.

Inside code, major blocks get a comment describing what that block does. This allows a reading of the code for intent, quickly, without having to dig into the gory detail of some variable declared 15 pages earlier. (Tell me what it does, and why. Don't tell me how. I can figure out the how from the code.)

Based on what I see from others leaving comments here, it would seem many of those would delete about 90% of the comments I write. Shame... adds to the entropy of the universe.

Answer 14

The only reason to ever put your name at the top of a file is when it is a homework assignment and your professor requires it to keep straight which student wrote the code he is looking at on a printout.