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.

This is something I was never taught. I have seen alot of different types of authoring styles. I code primarily in Java and Python. I was wondering if there was a standard authoring style or if everything is freestyle. Also if you answer would you mind attaching the style you use to author files that your create at home or at work.

I usually just go

@author garbagecollector
@company garbage inc.
share|improve this question

closed as primarily opinion-based by gnat, Bart van Ingen Schenau, Kilian Foth, MichaelT, Dan Pichelman Nov 5 '13 at 19:05

Many good questions generate some degree of opinion based on expert experience, but answers to this question will tend to be almost entirely based on opinions, rather than facts, references, or specific expertise.If this question can be reworded to fit the rules in the help center, please edit the question.

2  
Where does the person who changes your code put their name? –  JeffO Jan 7 '11 at 14:51
    
@Jeff where and how does it look. –  dustyprogrammer Jan 7 '11 at 15:09
    
It makes no sense to do that. Why would you want to do that? –  CodeART Apr 22 '12 at 22:20
add comment

11 Answers 11

up vote 0 down vote accepted

Not entirely sure what your asking, however I use a very strict style:

;==========================================
; Title:  Author Style Sample
; Author: Darknite
; Date:   7 Jan 2011
;==========================================

The style is inspired from assembly programmers.

I put this at the top of pages I need to "Author", regardless if this is a class, text file, or SQL stored procedure etc.

I don't know if that helps.

share|improve this answer
    
This is along the lines of what I am looking for. –  dustyprogrammer Jan 7 '11 at 15:10
4  
-1 This (which grows a lot if updated (both it and the code changes by various people) is effectively replaced by version control. –  Michael Durrant Mar 19 '12 at 12:39
1  
@MichaelDurrant you forgot to close your parenthesis ;) anyway cool. I like penguins. –  Darknight Mar 19 '12 at 12:42
3  
@Giorgio Not really...there might not be a single line of code of the original author left in the file. It's pointless. –  Wilbert Nov 5 '13 at 12:34
1  
@Wilbert: Of course, it also depends on the team's policy: with shared code ownership, it may be pointless to keep track of a file's author. With individual code ownership it is important to know who is responsible for which files. –  Giorgio Nov 6 '13 at 6:14
show 2 more comments

Why would you? that's the job of the versioning system and "Blame" :)

share|improve this answer
8  
version control ftw. –  Paul Nathan Jan 7 '11 at 16:03
1  
It makes even more sense to do it that way if you think of it as source code management (SCM) rather than version control system (VCS). –  Peter Eisentraut Jan 7 '11 at 17:18
    
small limitation, cosmetic changes (indentation, etc...) change the author of the line... –  Matthieu M. Jan 7 '11 at 17:41
4  
@Matthieu: Good SCM can show who made what changes over time, not just the last one to touch it. I might also argue that cosmetic changes are changes, too. –  grossvogel Jan 7 '11 at 19:35
    
@grossvogel: they are, and of course I expect a SCM to show me the full historic of a file. If it doesn't, I won't even consider it a SCM :) –  Matthieu M. Jan 7 '11 at 19:36
show 1 more comment

We don't do authoring at my company. Instead, we let our version control handle it.

Every time you check in, it attaches your user name to the change list. If something is broken, someone can go back and look at the change history to see what has changed, when, and who did it. It's also neat looking at the revision graph to see how a file has evolved over time, who's touched it, what projects have branched from it.

The problem I see with putting an author tag on a class is that over time it's pretty likely that more than one developer will be working on that class. Updates, and the like. It's an extra step to update that author comment, and extra small steps tend to get forgotten a lot. Thus it becomes out of date quickly.

share|improve this answer
add comment

I don't do that at all. I think at work we have some template that gets inserted in the files with the company name and userid of the person who last modified the file, but I never pay attention to that.

In general, I don't think it really matters how you do it. If you want to author-stamp your files, just pick a consistent style and go with it.

share|improve this answer
add comment

I think that's best left to the version control system.

share|improve this answer
add comment

JavaDoc is very much standard in the Java community:

http://download.oracle.com/javase/1.3/docs/tooldocs/win32/javadoc.html#@author

@author name-text

Adds an "Author" entry with the specified name-text to the generated docs when the -author option is used. A doc comment may contain multiple @author tags. You can specify one name per @author tag or multiple names per tag. In the former case, Javadoc inserts a comma (,) and space between names. In the latter case, the entire text is simply copied to the generated document without being parsed. Therefore, use multiple names per line if you want a localized name separator other than comma.

share|improve this answer
add comment

I like the blame feature in GIT. You can see who authored each piece/line of code. Not just a file.

share|improve this answer
    
Other VCSs have the same thing (albeit often not called "blame"). –  Richard Jan 8 '11 at 13:13
    
I would -1 this because it is GIT specific. OP never mentioned GIT. But alas, I don't have enough rep to downvote. –  Thomas Eding Apr 4 '12 at 20:06
add comment

If you are working on a large project with many contributors, annotating each file with list of authors just doesn't work. What do you do with the list of authors when you divide a file into several smaller files? Do you keep the original author name if you completely rewrite the code? Do you add your name to the list of authors when you fix a typo in comment?

These questions are better left for the version control system.

But I'm not completely against list of authors. Keeping a list of authors for the whole project makes perfect sense. If it's a single-file-project, sure, keep it inside that very file. If it's larger project keep it in README or your top level source file (aka main.c). But don't repeat yourself by listing authors in every single file.

share|improve this answer
add comment

We keep track using the version control system or by placing @author in the code. Another way to do it is to say more generally, that certain people were authors for whole modules or for the whole program. That encourages people to think of themselves as part of a team instead of as a cog in the machine that's responsible for exactly X number of functions or lines of code.

share|improve this answer
add comment

I use Doxygen style (or sometimes KernelDoc) comments for pretty much everything. I mostly work in C and PHP, where Doxygen is quite popular.

In most cases, It is helpful to at least include the following information:

  • Permission (or no) to copy it / Copyright of company or individual
  • Author Name / e-mail
  • Date written
  • Date last modified

That should help anyone who happens to be working on the file know what they have, what they can do with it and who they can ask for help if they need it. It also tells them if they're looking at something 10 years old.

share|improve this answer
add comment

I don't personally do this because it's extra documentation which like others said, is in the version control. But if I were going to make some sort of kung-fu code snippit, I'd probably be apt to go with whatever my IDE was capable of auto generating.

For instance, using in Delphi 7 with those helpful CNTools installed I type

///a [enter]

and out comes

//<author></author>

then I type

///d [enter]

and out comes

 //<date></date>

I'd imagine that corresponds to something some 3rd party utility can pick up on, but as for me - I've got a standard that I didn't even have to make up and corrupt myself.

share|improve this answer
add comment

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