maandag 10 maart 2014

Documenting @author in source code: graffiti or attribution?

Lately I am struck by how arbitrary certain practices and best practices really are. How many details our systems require of us and how many we gloss over with preconceptions picked up without critical thought or indeed any evidence beyond hearsay.

Take for example the @author tag. I recently found a bit of new code in a project I help maintain for a customer with an @author tag appended to the top.
I contacted the developer and asked why he'd added it. He said he'd seen some larger projects do it and he decided to try it out.
I on the other hand had heard something about it being bad and being obsoleted by VCS systems.

So I decided to ask / search around, here is what I found.

History

Most likely documenting the 'Author' in code did start out in the days before wide-spread adoption of revision control. A way to keep track of who had been working in what file. Though it seems odd as JavaDoc was created in '95 and RCS was available from '82? Honestly I wasn't around for that stuff and it's really poorly documented, hopefully someone can comment on this.
At least we know that in 95 it was codified in JavaDoc and from there copied into phpDoc, jsDoc, pydoc and other *doc systems.

So is @author deprecated then?

Well, 10 years ago Apache already thought so. It appears the designers of C# didn't even put the tag in.
Common wisdom for JavaDoc appear to be not to use the tag any more either.
But every *doc version I've found still appears to have it, so no, it's not deprecated officially.

So is anyone sill using it then?

I sampled some sources of popular PHP projects and came up with the following:

Popular Packages by repository organization on Packagist
 (Top 30):

  • [  ] psr
  • [X] monolog
  • [X] symfony / twig
  • [X] swiftmailer
  • [X] doctrine
  • [X] phpunit
  • [  ] guzzle
  • [  ] krisswallsmith
  • [  ] laravel
  • [  ] domniki
  • [  ] nikic
  • [  ] EllisLab (Code Igniter) (Dev Team)
  • [  ] yiifosft
  • [  ] WordPress
  • [  ] PHPOffice
Honorable mentions:
  • [  ] Drupal
  • [  ] Zend Framework 2
So basically, only PHPUnit and Symfony related projects appear to use the tag.

Why?

On twitter I had some replies from advocators of the tag and they had the following reasons:

  • Finding someone who can say more about the design of the component / class
    (so using the tag as if it was @architect or @contact).
  • Attribution to third parties (this algorithm is by ....).
  • For distributed source files, no longer under source control.
  • Because VCS is slow and cumbersome.
  • Tentatively: Copyright purposes? (I think @copyright is for that one)

Why not?

  • Duplicates VCS information.
  • Most likely out of date (created by Alice, but hacked into unrecognisable form by Bob) or at least hard to keep up to date.
  • Who is the author really? At what percentage of rewritten lines? What if you're doing it on company time?
  • Implies exclusive ownership, deterring contributions from others.

Also see the excellent Google Talk for more on the last argument against:
 How Open Source Projects Survive Poisonous People
                                       (And You Can Too) (skip to 20:05 for the relevant bit)


Conclusion

Is it possible to use @author effectively? Yes, I think so. It would be nice to see the author for a device driver buried in another product written 10 years ago for some obscure piece of hardware that I just happen to want to use.
But it takes a lot of discipline to keep it up to date and it slightly nudges people into thinking of code as 'owned' by someone, which is generally a bad thing both in Open Source and in commercial projects.
Also, the name doesn't really help. Perhaps a better name would be @collaborator? @architect? @contact?

Will I ever use it on my projects? No probably not, I'm just not that disciplined. And I'll probably still caution colleagues against it unless they have a very good reason.

Anyway, let me know what you think!

Thanks to @mvriel, @tvlooy, @keesvandieren, @scataco, @Martin1982@rosstuck, @ircmaxell, @bitfalls, @mwop and especially @Ocramius for input!