Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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.

share|improve this question

marked as duplicate by ChrisF Dec 21 '11 at 8:51

This question has been asked before and already has an answer. If those answers do not fully address your question, please ask a new question.

8  
I've inherited legacy code where the author's name and e-mail are the ONLY comments in the file... if that's your style, I advise not signing your files, as all it does is give the next person who inherits the code someone to direct their anger to. –  CamelBlues Aug 17 '11 at 20:56
add comment

14 Answers

up vote 66 down vote accepted

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.

share|improve this answer
2  
I've seen the history/commit comment log as well. I don't understand it. It's trivial to extract that information from any decent version control system. And if you can't get at that information easily from your VCS, you probably have larger configuration management issues that should be addressed. –  Thomas Owens Aug 17 '11 at 14:26
14  
@Thomas Owens, it used to be common practice back in the SCCS and RCS days to have the log embedded in the file at checkout time to make it visible inside the file you were working on. Particularly when you had a single terminal and could not easily switch, it did help somewhat to have it all in the same place. That would now be considered an archaic practice (to me at least) –  sdg Aug 17 '11 at 14:41
    
@sdg Oh RCS. RCS was my first version control system, back in 2006, when I was taking my first CS courses. I suppose it made sense back when RCS was actually widely used, now that you bring that up. But you're absolutely right that technological advances have made it an archaic practice. –  Thomas Owens Aug 17 '11 at 14:42
2  
One reason you might want to attach your name to a piece of code is if you personally own a patent or copyright for the algorithm that's implemented in that code. Otherwise the code (usually) belongs to the company who's paying you for your work. –  oosterwal Aug 17 '11 at 18:53
    
@oosterwal I would suspect that would be in the document that specifies the software license, to identify blocks of code that are under a different license or specially licensed for use/used with permission. If you include your license on all source files, maybe, but I wouldn't include it otherwise. –  Thomas Owens Aug 17 '11 at 19:42
show 1 more comment

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.

share|improve this answer
    
Just a quick comment: in some corporate environments tracking the user name back through the VCS can be very difficult. When user names are of the form QX182457 - you want to know the name not the corporate drone ID number. –  quickly_now Dec 21 '11 at 6:10
add comment

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.

share|improve this answer
    
A number of reasons have been given here. –  Paul Nathan Dec 21 '11 at 7:58
add comment

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.

share|improve this answer
add comment

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:)

share|improve this answer
1  
+1 I'm a habitual code stripper too. If I'm reading code and I encounter any comment that doesn't further my understanding of it, it's toast. –  JohnFx Dec 21 '11 at 5:07
    
Not a good attitude. Perhaps you should consider why they were written in the first place. I assume you would strip my company name details, author information, file purpose / summary... –  quickly_now Dec 21 '11 at 5:51
1  
Why were they written in the first place? What value does company, author name offer. I believe intent of code should be obvious from the code itself. Comments are notoriously unreliable way of documenting code as they are rarely kept in line with the code. Comments are a smell covering badly written code a lot of the time IMHO. –  Chris Lee Jan 5 '12 at 11:05
add comment

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

share|improve this answer
2  
I was hoping someone would have said this. –  John Aug 17 '11 at 22:24
22  
I don't see the connection. You can take pride in producing quality work without explicitly signing your code. –  Dennis Aug 18 '11 at 6:49
10  
Do you also take pride in seeing your name still at the top of the file when someone else has introduced a dozen crazy bugs? –  Peter Taylor Aug 25 '11 at 7:23
4  
@bjarkef: You can only do that if you still work there. What if you leave, some idiot picks up your project and injects dozens of bugs, and the next reasonable programmer who has to work on the code sees your name at the top? Great way to ruin your reputation... The source code commit logs show what you produced and what you didn't, which is a far more reliable way of "signing" your code. –  Ant Aug 25 '11 at 9:32
3  
I take pride in producing code that is bereft of useless comments that exist only to stroke my own ego at the expense of making everyone else trudge through them. –  JohnFx Dec 21 '11 at 5:04
show 2 more comments

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.

share|improve this answer
2  
Um, right, but in a good VCS he could find out the needed information easily anyway. –  Scorchio Aug 17 '11 at 20:38
3  
@scorchio: Did you even read what I wrote? The vast majority of people who use my code don't have access to my VCS, so how would that help them? –  Satanicpuppy Aug 17 '11 at 20:53
3  
Actually, I did, that's why I've said "in a good VCS". For example with Git it takes almost nothing to pass the repo around, so they could have access to all the version control data. –  Scorchio Aug 17 '11 at 20:56
3  
@scorchio: I don't send repos to people. I send finished, deployable code. –  Satanicpuppy Aug 17 '11 at 21:26
1  
@Satanicpuppy: Valid point. However, deployable code typically is compiled (unless it's a scripting language), so the point about comments is moot. –  sleske Aug 25 '11 at 7:23
show 6 more comments

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.

share|improve this answer
3  
replace "your name" with "your companies name" and it becomes useful again –  jk. Aug 17 '11 at 15:25
    
I have the feeling that the Average Coder Joe couldn't care less about his name in a file, perhaps added automatically by an IDE or something... –  Scorchio Aug 17 '11 at 20:48
2  
You're putting your name on it when you check it in under your account. Putting your name in the file is unnecessary even for that purpose. –  Wyzard Aug 18 '11 at 3:37
    
@Falcon: I know this is a very old post, I read it few weeks ago but I just finally finished reading The Pragmatic Programmer and came across the last chapter where the authors mentioned signing code. I think the authors made a very good point. In fact, they explicitly called out that signing/owning work is not the same as nobody ever touches the source file. But it means that the file has a keeper. I've been on the other side of the coin way too many times, when the code becomes anonymous, as the book predicts, nobody cares and it quickly goes from broken windows to cars on fire. –  DXM Dec 27 '11 at 9:25
add comment

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...

share|improve this answer
2  
My IDE automatically puts usernames -- thanks for mentioning! made me re-check my IDE settings, find File Header template and wipe out all the dumb stuff that was there, including User: ${USER} :) –  gnat Aug 17 '11 at 15:26
add comment

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

share|improve this answer
    
Which VCS are you using, if I can ask? –  Scorchio Aug 17 '11 at 20:49
    
we use subversion –  oenone Aug 18 '11 at 6:25
2  
The correct answer is they use subversion AND an archaic comment based system for no good reason at all other than it looks pretty. –  JohnFx Dec 21 '11 at 5:07
add comment

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.

share|improve this answer
1  
Yeah. I don't even want to imagine who will maintain this kind of comments after forking the project for example. That's just too tedious. –  Scorchio Aug 17 '11 at 20:40
    
My thought exactly, especially given that blame tells you who wrote it line-by-line rather than just one name for the entire file (which may actually have several authors by the time you look at it). –  Dave Sherohman Aug 25 '11 at 9:02
add comment

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.

share|improve this answer
1  
" comments ... indicating the change made and why with your name". Usually version control systems ( at least svn and git) offer a "blame" feature that allows you to know who was the last to modify a specific line of code. So, even there, I see no need to add your name in the comment. –  David Aug 18 '11 at 8:22
2  
Oh, my point was less about accountability, and more about "This looks odd, and here's why..." so that you can justify it before it's posted on thedailywtf.com. –  Shawn D. Aug 18 '11 at 13:00
    
sure, that's the point of the comment, so there's no need to add your name. –  David Aug 18 '11 at 15:31
    
Sometimes the source control is replaced (in my last company sourcesafe to git) and looking for a class by class name in the previous source control system can be more and more cumbersome for a large code base as time passes and code is refactored. I don't think it's a bad idea at all to keep a reference in the code to the person who originally designed it. –  Jubbat Jun 12 '13 at 13:43
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
5  
Don't you use source control? –  user1249 Aug 17 '11 at 14:17
10  
@temptar That's no excuse. Even a legacy project can be added to source control at any time. –  Thomas Owens Aug 17 '11 at 14:19
9  
Consider spending time on bringing in source control anyway instead of spending time on doing the source control systems work manually. It will save your employer considerable amount of time and money at a later time - much like a fire alarm. –  user1249 Aug 17 '11 at 14:21
3  
Ah, mainframes! You Can still get source control even for those. –  user1249 Aug 17 '11 at 14:56
3  
@temptar, we don't want to offend you; could you tell us more about your environment (if it's not confidental info of course)? It's really hard for me to imagine any OS or device without an option for VCSs. –  Scorchio Aug 17 '11 at 20:43
show 4 more comments

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