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.
Improve this question
3
  • 3
    Where does the person who changes your code put their name?
    – JeffO
    Jan 7, 2011 at 14:51
  • @Jeff where and how does it look.
    – myusuf3
    Jan 7, 2011 at 15:09
  • It makes no sense to do that. Why would you want to do that?
    – CodeART
    Apr 22, 2012 at 22:20

11 Answers 11

Reset to default
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.

Improve this answer
7
  • This is along the lines of what I am looking for.
    – myusuf3
    Jan 7, 2011 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, 2012 at 12:39
  • 1
    @MichaelDurrant you forgot to close your parenthesis ;) anyway cool. I like penguins.
    – Darknight
    Mar 19, 2012 at 12:42
  • 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 5, 2013 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, 2013 at 6:14
76

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

Improve this answer
7
  • 9
    version control ftw.
    – Paul Nathan
    Jan 7, 2011 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, 2011 at 17:18
  • small limitation, cosmetic changes (indentation, etc...) change the author of the line...
    – Matthieu M.
    Jan 7, 2011 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, 2011 at 19:35
  • 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, 2019 at 6: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.

Improve this answer
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.

Improve this answer
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.

Improve this answer
5

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

Improve this answer
4

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

Improve this answer
2
  • Other VCSs have the same thing (albeit often not called "blame").
    – Richard
    Jan 8, 2011 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, 2012 at 20:06
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.

Improve this answer
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.

Improve this answer
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.

Improve this answer
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.

Improve this answer

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