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?

Here's several scenarios which may comment with owner name:

  1. bug fixing, i.e. // fixed bug 123 by xxx, solution is ... ...
  2. fixme/todo tags, i.e. // TODO: .... by xxx.
  3. hacks, i.e. // HACK! ... by xxx

For case #2, please refer to Comment Tags

The obvious advantage is that we can ease tracking by names. The downside is the risk of abuse. Actually my previous company allowed this way of commenting style, but current employer completely disallows names appearing in code.

In my opinion, I would vote for discreetly commenting with author names. I'm open to hear from you if this commenting style is good or bad. Thanks.

share|improve this question

marked as duplicate by Yannis Rizos, Caleb, 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.

1  
    
This linked questions aren't really the same. This Q is about signing comments on code that may or may not have been written by the commenter. –  MatthewMartin Dec 21 '11 at 3:54
    
While this question is not identical to previous ones, "What are you guys doing?" is not really a question that fits the faq. It's an open ended question with no obvious answer. It could be improved, but the only ways I could think of improving it would actually make it identical to one of the two S.Lott pointed out. What the answers here point out can be extracted from the similar questions' answers (or are too localized), and if op read them before asking this question it might have been a quite different one (read: better one). Voted to close. –  Yannis Rizos Dec 21 '11 at 4:17
    
It's not good or bad. It's HORRIBLE. –  JohnFx Dec 21 '11 at 5:02
    
@JohnFx And that's a horrible comment, according to the guidelines –  Yannis Rizos Dec 21 '11 at 6:22
add comment

3 Answers

up vote 11 down vote accepted

First, you should never have comments like this in your code. Neither with author's name, nor without. A name helps, since it indicates who must be blamed to ignore the most elementary rules of commenting code.

For example your first example is a comment which talks about a bug being fixed. Why would a person reading the code bother about what you solved and when? There was a bug. It is solved now. So don't bother the readers about the fact that the code was buggy in the past.

A comment in a code must help to understand what this code is doing. Not what the code failed to do in the past.

Your second example is not a good one neither. There are bug tracking tools for that.


Second, there are plenty of reasons to avoid people names in comments.

  • Comments get quickly obsolete. Let's say I'm proud of a method I wrote, and I really want to put my name in a comment, so everyone will know I'm this smart author who got this genius idea. A month later, my colleague refactors the method. A month later, some other person modifies it. A month later I'm fired from the company because I didn't know how to use comments. I month later, another developer makes substantial changes to the code. Here we are, there is no line left from what I've written, and still the comment says that I'm the one who typed the actual code.

  • Comments don't follow the changes in a team. What if the code was written by Joe, Joe left a company ten years ago, and now there are two new Joe's in the company? Does it make sense to read in a comment that a piece of code was written by Joe?

  • Don't duplicate what is already provided by version control logs. Those logs are not here "just because they do". They allow, at any moment, to know precisely who did what and when.

  • Comments lie. And may contain mistakes, in general. What if I put my name on someone's else code, just by mistake? At least a version control log don't lie, and don't have mistakes.

  • Put names... to do what? Blame people for bugs? Be proud of your code? In both cases, there are more serious problems in the company and the relations between coworkers to consider before asking if names must be put in comments or not. As a part of a team, you contribute to a common codebase. If there is no shared code and everyone is working on a separate part of a code, then what's the point in having a team of developers?

  • Last but not least, like I said before, the sole purpose of a comment is to help to understand code. Knowing the name of a person who did something with the code hardly tells you what the code is actually doing.

share|improve this answer
    
Sure version control could help in similar way, but it doesn't happen in place which code exactly locates. There might be another topic, make every change small and isolate. –  fifth Dec 21 '11 at 3:53
    
+1 because that is all I have to give. I Hate, Hate, Hate when programmers add comments like the examples given by the OP. I don't give a rat's ass about the history of the code and if I did I would use the SCM tool which has far superior ways of visualizing the information. –  JohnFx Dec 21 '11 at 5:01
    
I would defend some of the practice of placing in comments that something fixed a bug, especially if the fix isn't at all obvious. Comments should explain why the code is doing something, and if that why is because it fixed some bug that only occurs in the Lebanese version of windows, why not say so? –  whatsisname Dec 21 '11 at 5:46
    
This is quite a rigid view. Sometimes a comment like "fixes bug 3142" is helpful to explain why a piece of code is the way it is. Without it, a reader might wonder "why didn't the author take a more straightforward approach?" Instead of repeating a lengthy explanation in a comment, a simple reference to an issue in the tracking system explains it. TODO comments can help mark a work in progress (programming isn't always a linear activity), and one can argue that they should always have a name attached. –  Caleb Dec 21 '11 at 6:03
    
"At least a version control log don't lie, and don't have mistakes." uhh, really? There are these things called bugs. Yeah, BUGS. They are these things that are unintentional... well, google it, why don't ya. –  Thomas Eding Apr 4 '12 at 20:10
add comment

At one previous employer, the commenting style consists of:

// 20DEC11. ABC. Bug 126230, Iterator is off by one when reading from networked drives.

Where ABC is the developer's initials. This company has been shipping "shrinkwrap" software for over 17 years, and has migrated through about 5 different version control programs. The version history for some files are in the hundreds of revisions, so forcing some sucker to try to sift through 300+ revisions is cruel punishment. The corporate parent would occasionally compel offshoring of some parts, so the date had to be set in the (old) Army way (with 2 digit years), so that one didn't get all sorts of strange numbers for December 20, 2011, like 12/20/2011 or 20/12/2011.

Alternatively, some look like:

// 20DEC11. VBS. ABC. Task 126230, Check annual IRS limits for Roth IRA detectability.

Where VBS stands for "verify before shipping" and represents magic numbers set by statute or regulations that must be checked annually. Nothing else may have those 3 letters in them, and you must never delete one of those comments.

share|improve this answer
1  
That makes my eyeballs itch just looking at it. –  JohnFx Dec 21 '11 at 5:02
    
Seems like a very sensible format. @JohnFx I think any unfamiliar syntax seems unpleasant at first. I bet you'd see these comments quite differently after just a day or two of working with code where they're used consistently, and at that point they'd seem much more useful. –  Caleb Dec 21 '11 at 6:13
add comment

I think the pattern that could trigger is a mini-discussion in the source code file.

// LRF- We should refactor this code
// John Q Public aka JQP- No, lets defer this until after version 4. 
//                        Don't stir up any mud.
// LRF- Several branches of the if-then logic aren't covered by unit tests
// JQP- Not interesting, they are edge cases not expected in production

Discussions in code comments evolve too slowly to be effective-- it could be years before another developer reads the comments you just wrote. In a beautiful world there would an IDE and source control integrated code review and discussion system with notifications to interested parties for each new comment.

In the meanwhile, where there are still shops that don't even have source control yet, from time to time you will see these mini discussions (or the start of them) in source code.

share|improve this answer
add comment

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