50

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.

regularfry
  • 701
  • 1
  • 6
  • 8
  • 11
    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
  • @CamelBlues Agreed. Name and e-mail message in most files are 2 comments too many. (I strive to write code that is clear without any comments at all. It’s possible in most languages—though not all—and leads to better quality code.) – Marnen Laibow-Koser May 06 '19 at 18:47

14 Answers14

79

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.

Spoike
  • 14,765
  • 4
  • 43
  • 58
  • 3
    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
  • 15
    @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
  • 1
    @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
  • We rely on the VCS for this for our compiled code, but for our database elements (SPs, views etc) we like to have the history in the file header. That way if we need to look at a particular customer's database, we can tell what version we sent them. And on the odd occasion, comparing their versionX to the VCS versionX reveals that they've made changes. – DaveE Aug 25 '11 at 17:40
  • @DaveE (yeah, I know, I’m replying years later) I’d say that your build/release process should add that info to the files; it’s generally derivable from the VCS and needn’t be stored separately *for your internal operations*. – Marnen Laibow-Koser May 18 '20 at 23:45
  • 1
    @MarnenLaibow-Koser That assumes we *have* a build/release process for our database code :) TFS doesn't do keyword substitution on check-in. – DaveE May 20 '20 at 00:20
  • @DaveE Why yes, it does assume that. Migration scripts are wonderful things. – Marnen Laibow-Koser May 21 '20 at 01:03
  • @MarnenLaibow-Koser not under my control. I just get to live with the results, unfortunately. – DaveE Jun 11 '20 at 23:41
24

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.

Shawn D.
  • 1,361
  • 1
  • 12
  • 14
  • 2
    " 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 08: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
  • 1
    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. – DPM Jun 12 '13 at 13:43
  • @DPM You could have and should have imported the history when you switched VCSs, then. – Marnen Laibow-Koser Mar 26 '19 at 04:26
18

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

Paul Nathan
  • 8,560
  • 1
  • 33
  • 41
  • 2
    I was hoping someone would have said this. – John Aug 17 '11 at 22:24
  • 30
    I don't see the connection. You can take pride in producing quality work without explicitly signing your code. – Dennis Aug 18 '11 at 06:49
  • 21
    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 07:23
  • @Peter: No, but I will discover it, fix the bugs and go smack the guy who introduced them and tell him what he did wrong. – Bjarke Freund-Hansen Aug 25 '11 at 07:37
  • 5
    @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 09:32
  • http://pragprog.com/the-pragmatic-programmer/extracts/tips I am sorry that your coworkers introduce bugs. – Paul Nathan Aug 25 '11 at 16:12
  • 10
    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 05:04
  • 1
    The problem is that modern IDEs will automatically add your name to the top of the file when it's created. That's not signing your work, it's signing a blank document. I.e., it's signed before the fact, somewhat like signing a blank cheque. I agree with taking pride in your work, but I see no value in declaring who created a file, since over time, the "ownership" can change as other developers work on it. P.S. I do think that _The Pragmatic Programmer_ is an excellent book, and this is one of the few things I disagree with. That advice probably made more sense before version control systems. – CJ Dennis Aug 16 '17 at 03:05
  • @CJDennis What “modern IDE” does that? I’ve never seen it. – Marnen Laibow-Koser Mar 26 '19 at 04:26
  • 1
    @MarnenLaibow-Koser PhoStorm does it out of the box. There isn't even a setting to turn it off, you have to edit the template files. – CJ Dennis Mar 26 '19 at 06:55
  • @CJDennis Wow. (I’ve never used PHPStorm, so I didn’t know that. I suppose I might use PhoStorm for developing Vietnamese soups. :) ) – Marnen Laibow-Koser Mar 26 '19 at 14:43
16

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.

Falcon
  • 19,248
  • 4
  • 78
  • 93
  • 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
  • 3
    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 03: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 09:25
  • @DXM Collective code ownership is a good thing. On a team, the keeper of the code is the team. If any one person becomes keeper of any one file, then the team has failed. On a team where people take pride in their work, this does not lead to the tragedy of the commons that you’re describing. (I have been fortunate to mostly work on teams where people take pride in their collective work...) – Marnen Laibow-Koser Mar 26 '19 at 04:28
  • 1
    @MarnenLaibow-Koser - unfortunately that DXM from 8 years ago doesn't exist anymore. For all intents and purposes he is dead, so he can't really defend his point of view here. But yeah, I'm absolutely onboard with you. – DXM Mar 26 '19 at 20:14
  • @DXM Nicely put! Of course our views all change and evolve. – Marnen Laibow-Koser Mar 26 '19 at 21:38
12

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.

Dan Ray
  • 9,106
  • 3
  • 37
  • 49
  • 2
    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
  • 1
    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 09:02
7

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

Chris Lee
  • 278
  • 1
  • 6
  • 2
    +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 05: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 05:51
  • 2
    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 05 '12 at 11:05
5

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.

Thomas Owens
  • 79,623
  • 18
  • 192
  • 283
  • Agreed except for the idea that mandating a coding style is a good thing. In decades of development, I’ve never seen a mandated coding style improve a codebase; usually it simply provides a foolish consistency and makes some parts of the code *less* easy to understand. For myself, I don’t care if every file is in a different style as long as all the code is readable and of good quality. – Marnen Laibow-Koser Sep 16 '19 at 22:37
5

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.

Satanicpuppy
  • 6,210
  • 24
  • 28
  • 3
    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
  • 4
    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 07:23
  • @sleske: In my industry it's pretty common to pass source around among different business units. Even with compiled code, I put my name on the config files, so when there are issues, they know who to call. – Satanicpuppy Aug 25 '11 at 13:21
  • 1
    @Satanicpuppy: Ah, interesting. Have you considered using something like Maven + companywide repository, rather than just exchanging source files? – sleske Aug 25 '11 at 14:02
  • @sleske: Effectively impossible, I'm afraid. We're not remotely standardized, and any attempt I made to push something like this would devolve into a pissing contest among larger business units about what sort of repo, who'd host it, code naming conventions...Yuck. – Satanicpuppy Aug 25 '11 at 14:14
  • 1
    If I wrote code that required people to call me for "support" on it, I'd probably prefer to remain anonymous. – JohnFx Dec 21 '11 at 05:08
  • @JohnFx: Nothing like a user who wants to chime in 3 months after the question is closed, just to make a snide remark. I leave my name on it in case they need to add new features, or lose the documentation, or have any questions. If your code is so simple that it never needs to be supported, then no, you probably wouldn't want to put your name on it. I, on the other hand, just made 5k modernizing some Java code from 2000. Yay me. – Satanicpuppy Jan 09 '12 at 19:18
  • 1
    And you don't use source control which tracks this exact information? – JohnFx Jan 09 '12 at 20:22
4

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

jhocking
  • 2,641
  • 19
  • 18
  • 3
    _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
  • This is the second time I’ve seen this mentioned. What IDE does this?!? Please let me know so I can avoid it. – Marnen Laibow-Koser Mar 26 '19 at 04:31
  • I haven't used it in years so I don't exactly recall, but I think it was Eclipse. – jhocking Mar 29 '19 at 01:39
3

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

Rommudoh
  • 412
  • 2
  • 7
1

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.

temptar
  • 2,756
  • 2
  • 23
  • 21
  • 5
    Don't you use source control? –  Aug 17 '11 at 14:17
  • Environment doesn't allow for it at present. Legacy. – temptar Aug 17 '11 at 14:18
  • 11
    @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
  • 11
    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. –  Aug 17 '11 at 14:21
  • 2
    Joel test Fail ... – IAbstract Aug 17 '11 at 14:21
  • 2
    Environment doesn't allow for it...? Both Git and SVN run on Windows, Mac, and a dozen flavors of Linux. Are you coding on a smartphone? – Michael Moussa Aug 17 '11 at 14:35
  • 1
    None of these things as it happens. – temptar Aug 17 '11 at 14:36
  • 3
    Ah, mainframes! You Can still get source control even for those. –  Aug 17 '11 at 14:56
  • 4
    @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
0

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.

back2dos
  • 29,980
  • 3
  • 73
  • 114
0

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.

quickly_now
  • 14,822
  • 1
  • 35
  • 48
  • 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 06:10
  • I’d delete closer to 100% of the comments you write. Your name comments are largely useless, and the filename completely so. As for the block comments, as you describe them, they have *negative* value, as they’re masking problematic areas in the code. If a variable is declared 15 pages from where it’s used, don’t rely on a comment to improve the code; rather, refactor it so that the variable can be declared closer to where it’s used, so that you don’t need the comments. Likewise, if a comment expresses some invariant property, make it an automated test. Comments mean the code isn’t done yet. – Marnen Laibow-Koser Sep 16 '19 at 22:49
  • In reply to Marnen Laibow-Koser: If you think that code with comments is not "done", then I regard you as selfish and immature, who has no consideration of those who come after to look at the code to figure out what it does. You'd never get a job at my company. – quickly_now Sep 12 '21 at 06:03
  • And I’d never want a job at your company, if you think comments are an acceptable palliative for bad code. I do write comments to indicate things that are external to the code itself, such as waiting for a pull request to be merged or identifying the source of an algorithm. I also recognize that there are a few languages [notably assembly] where it’s almost impossible to write clear code without comments; I don’t do much work in these languages. But other than these types of situation, in 20 years I haven’t seen a comment that wasn’t covering up a problem with the code. – Marnen Laibow-Koser Sep 13 '21 at 12:23
  • About having no consideration of those who come after: no, it’s precisely *because* I want those who come after to be able to read my code that I don’t rely on comments. Instead, I make the *code* comprehensible to those who come after me. I’d regard relying on comments to explain code as immature. It’s a stage we all go through as programmers—I surely did—but I’m happy to have left it behind, and my code is better and more readable for having left that practice behind. – Marnen Laibow-Koser Sep 13 '21 at 12:29
  • Contentious answer.... all the points are gone! Interesting how some people have not written code for professional companies where coding standards require comments, and will be rejected in review if they are not there. Imagine looking at time critical code, low level, working in an embedded microcontroller, and no comments to guide as to the authors intentions! – quickly_now Sep 19 '21 at 10:23
  • As I implied with my comment about assembly language, I can well believe that things are different in (some) low-level languages, but I have little experience with that kind of work. Still, though, I don’t trust comments as a guide to the author’s intentions, because it’s easy for them to get out of sync with the implementation, so I generally ignore comments when reading code, or at least take them with a large grain of salt. Far more useful as a guide to the author’s intentions are automated tests (if the environment allows for them), since they will fail if they get out of sync. – Marnen Laibow-Koser Sep 20 '21 at 12:20
  • And I have written code for professional companies for two decades. Not every place I’ve worked has had any sort of standards regarding comments, but if they do, the standard is generally “don’t write them”, for precisely the reasons I’ve been explaining. – Marnen Laibow-Koser Sep 20 '21 at 12:23
-1

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.

JohnFx
  • 19,052
  • 8
  • 65
  • 112