15

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.
MIA
  • 5,264
  • 19
  • 29
myusuf3
  • 2,084
  • 3
  • 18
  • 28

11 Answers11

76

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

Homde
  • 11,104
  • 3
  • 40
  • 68
  • 9
    version control ftw. – Paul Nathan Jan 07 '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 07 '11 at 17:18
  • small limitation, cosmetic changes (indentation, etc...) change the author of the line... – Matthieu M. Jan 07 '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 07 '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 07 '11 at 19:36
  • +1 for Blame!!!! My favorite! (though in the TFS world they took some of the fun out and called it Annotate. We know the truth.) – sq33G Dec 21 '11 at 09:06
  • 1
    This answer is more than 8 years old, and noone noticed its restrictions? It applies only if the source code stays in one VCS over its whole life time (or is properly migrated)! However, lots of open source codes are transferred between different environments from time to time, so the author information might not be passed over if it is not written directly into the source code. – Doc Brown Jun 13 '19 at 06:13
11

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.

Tyanna
  • 9,528
  • 1
  • 34
  • 54
10

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.

Adam Lear
  • 31,939
  • 8
  • 101
  • 125
6

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.

gnat
  • 21,442
  • 29
  • 112
  • 288
Luca Matteis
  • 699
  • 1
  • 5
  • 12
5

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

Tundey
  • 227
  • 2
  • 6
4

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

chiurox
  • 1,498
  • 12
  • 17
2

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.

Rene Saarsoo
  • 156
  • 5
1

Not entirely sure what you're 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.

Josh Correia
  • 107
  • 4
Darknight
  • 12,209
  • 1
  • 38
  • 58
  • This is along the lines of what I am looking for. – myusuf3 Jan 07 '11 at 15:10
  • 5
    -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
  • @Michael Durrant: Even with version control it is useful to know who was the initial author of a file and when the file was created without having to look at the version control system's log. – Giorgio May 25 '12 at 17:40
  • 4
    @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 05 '13 at 12:34
  • @Wilbert: I agree, but this should be a fairly rare situation. If this happens too often, then the code base is very unstable. In particular, the team is probably not following the open/closed principle (http://en.wikipedia.org/wiki/Open/closed_principle) and is continuously rewriting code that had already been tested and released. – Giorgio Nov 06 '13 at 06:11
  • 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 06 '13 at 06:14
1

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.

0

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.

Tim Post
  • 18,757
  • 2
  • 57
  • 101
0

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.

Peter Turner
  • 6,897
  • 1
  • 33
  • 57