Get Rid of Source Code Templates

by Ville Laurikari on Tuesday, April 14, 2009

Have you ever seen a project where all files begin with something like this?

/*
 *
 * some-file.cxx                    __ _ _
 *  ___  ___  _ __ ___   ___       / _(_) | ___   _____  ____  __
 * / __|/ _ \| '_ ` _ \ / _ \_____| |_| | |/ _ \ / __\ \/ /\ \/ /
 * \__ \ (_) | | | | | |  __/_____|  _| | |  __/| (__ >  <  >  < 
 * |___/\___/|_| |_| |_|\___|     |_| |_|_|\___(_)___/_/\_\/_/\_\
 *
 * Version:  234
 *
 * Authors:  Jack McRabbit <jack at example.com>
 *           Mr. Coder <mr at example.com>
 *           Joe Trainee <joe at example.com>
 *           Ifixed Atypo <typo at example.com>
 *
 *********************
 *
 * Copyright (c) 2000,2001,2002,2006-2008,2009  ZingFindle Corporation
 * All Rights Reserved.
 *
 *********************
 *
 * IN NO EVENT SHALL ZINGFINDLE CORPORATION BE LIABLE FOR ANY DIRECT, INDIRECT
 * CONSEQUENTIAL, BLAH FLURB LEGALESE HERE, ARE YOU ACTUALLY READING THIS;
 * EVEN WHEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, BOB'S YOUR UNCLE.
 *
 * This is not a life-saving device and must not be used to build one,
 * or a medical device, oh, and also, this is not something you'd want
 * to put in a nuclear power plant, or anything else for that matter.
 * In fact, you'd be wise to print a copy, destroy all other copies,
 * including electronic copies, burn the printout, dissolve the ashes
 * in acid, and bury the waste into a hole in the desert.
 *
 * The above copyright notice and this permission notice must be included
 * in all copies of this file.
 *
 *********************
 * ChangeLog:
 *
 *   ifixed@rev 234: Updated copyright headers
 *   ifixed@rev 233: Fixed typos in changelog
 *   joe@rev 232: Added flooEnum.
 *     <231 more lines of this...>
 *
 **********
 *
 * TODO: ??
 *
 **********
 *
 * Description: write me
 *
 ****
 *
 */

I bet you have.  Most projects have some kind of standard source code template which has the copyright and license text and placeholders for things like a description.  All I have to say is: You don’t need a template Stop using it.

Actually, that’s not all I have to say.  Sorry.  If you believe me already, you can stop reading now and go do something useful with your life.  If you don’t quite believe me yet, please read on.

Why you don’t need to assert copyright

The most common objection to getting rid of these templates goes something like this:

“Hold on.  We must keep at least the copyright notice in place, surely?  We don’t want this to end up in the public domain or anything.  A template is the best way to make sure everyone always puts a copyright in.”

No, and no.  You don’t need a copyright notice in every file.  Even if you did, a template is not a good mechanism to do it.

You don’t need to assert copyright because of the Berne Convention for the Protection of Literary and Artistic Works.  It’s an international agreement which governs copyright.  Almost all of the world has signed the convention by now:

Berne Convention signatory countries (in blue).

The convention lays down the basics of what copyright is and what it means, and then says that “the enjoyment and the exercise of these rights shall not be subject to any formality”.  This means that you don’t need to do anything to have copyright over your works. You don’t need to include a “Copyright ©” text.  You don’t need to update copyright years, or figure out when to update them.  I mean, should it be updated every time the file is edited?  Or automatically at the turn of the year?  Should each year be separately listed, or can I just give the first and last year?

You can include a copyright text, but the Berne Convention says it has no legal meaning.  I say it’s useless baggage, especially the copyright years, so don’t put them in there at all.

Another common objection to leaving the copyright notice out goes like this:

“Everyone always puts a copyright notice in their files.  There must be something to it, otherwise they wouldn’t do it.”

At this point, I would like to remind you of the story of the five monkeys.

Start with a cage containing five monkeys.  Inside the cage, hang a banana on a string and place a set of stairs under it.  Before long, a monkey will go to the stairs and start to climb towards the banana.  As soon as he touches the stairs, spray all of the other monkeys with very cold, high-pressure water.  After a while, another monkey makes an attempt with the same result all the other monkeys are sprayed with cold water.  Pretty soon, when another monkey tries to climb the stairs, the other monkeys will try to prevent it.

monkeyNow, put away the cold water.  Remove one monkey from the cage and replace it with a new one.  The new monkey sees the banana and wants to climb the stairs.  To his surprise and horror, all of the other monkeys attack him.  After another attempt and attack, he knows that if he tries to climb the stairs, he will be assaulted.  Next, remove another of the original five monkeys and replace it with a new one.  The newcomer goes to the stairs and is attacked.  The previous newcomer takes part in the punishment with enthusiasm!

Likewise, replace a third original monkey with a new one, then a fourth, then the fifth.  Every time the newest monkey takes to the stairs, he is attacked.  None of the monkeys that are beating him have any idea why they were not permitted to climb the stairs or why they are participating in the beating of the newest monkey.  After replacing all the original monkeys, none of the remaining monkeys have ever been sprayed with cold water.  Nevertheless, no monkey ever again approaches the stairs to try for the banana.  Why not?  Because as far as they know that’s the way it’s always been done around here.

And that, my friends, is how company policy begins.

Before the United States had signed the Berne Agreement in 1989, a copyright assertion was actually required if you wanted to enforce your copyright in the US.  Everybody is still doing it, even though nobody needs to.

Why you don’t need the rest of it, either

Often, source code files repeat the file name in the file itself.  I’ve never seen the point in that.  It’s just one extra thing you need to remember to update if you rename the file.  A big ASCII banner with the file name is positively crazy, but some people do that, too.

A list of authors is quite useless, as are version numbers and change logs.  Any version control system will give you much better and much more accurate information for these automatically.

I also object to putting in a big fat license text to the beginning of each and every source code file, as is suggested in the GPL.  If you want to later change the license to something else, you have a lot of work ahead of you.  I’m not sure, but that may actually be why the GPL advocates putting in all that legal verbiage in every file.  In my opinion, a concise reference to a separate license file should be enough.

A TODO list and a description are actually good to have.  Sadly, these are the parts which most often are not filled in.

What you should do

stop-signFor source code that you never plan to release to outsiders, you don’t need any standard header, template, license, or copyright.  None.  All you need to do is put the code in version control, so you can use the logs to prove that you wrote the code, and when you wrote it.

If you really feel you must at least refer to a license in open source code, you should be fine with just one line in each file.

If you do this, I don’t much care what you then put in the “LICENSE” file.  You can put in all the copyright assertions and years for all I care.  Just stop being a monkey; don’t borify the source code with attention stealing enterprisey legalese and copyrights.

/* See the file "LICENSE" for the full license governing this code. */

Oh, almost forgot.  I am not a lawyer.  This is not legal advice.  Having to say that is stupid.

Related posts:

  1. Programming Problems in Disguise

If you liked this, click here to receive new posts in a reader.
You should also follow me on Twitter here.

Comments on this entry are closed.

{ 25 comments }

CAJeepBoy April 15, 2009 at 01:50

Nice writing style and good content. Thanks for the post! (^_^)

Ville Laurikari April 19, 2009 at 16:26

I’m glad you liked it. Just subscribe for more ;)

Markus October 19, 2009 at 15:53

> Often, source code files repeat the file name in the file itself.
> I’ve never seen the point in that.

In times long gone, when printing multi-file programs on a line printer, such a header was a good idea. I still remember the days when access to a video terminal was granted on a hourly basis, and printing your program and editing on paper to prepare for the next terminal session was the norm.

Ville Laurikari October 19, 2009 at 16:10

I still occasionally print code so that I can review it later armed with pens of different colors. That probably puts me in a minority of some sort. The tools I use for printing add a header with the file name automatically.

If anyone could point me to a nice web-based tool which would allow me to scribble “margin notes”, doodle pictures, and highlight pieces of code electronically, and share those notes with someone, it would be greatly appreciated.

Commenter April 3, 2010 at 13:31

Great post and good advice.

You’re missing the point though, especially on the copy-right notice IMHO.

Are they NECESSARY? No.

…but that’s not what matters. The real question is: Are they USELESS?

The fact of the matter is they do server a purpose.

I’m well aware that a copyright notice is not necessary legally. You hold copyright ipso facto when you create something.

…but that’s not why I put it on some things I distribute. It’s there as a subtle cue to my users that I have a certain way I would *like* them to use whatever I am distributing.

It may be that I just want them to contact me first, it may be that I have a special version already to give out rather than them trying to dis-assemble the one with the notice and re-purpose it, or any number of things.

Does it force them to use it as I intended or would like? No…but it *definitely* helps.

The other important question is: is it hurting anything?

Again, the answer is often no.

I agree many people take it out of hand. You don’t need to slap (c) all over *everything*. Having the file name is a bit silly….likewise the entire text of the license. Having it at the top of every file of a project is a mostly useless maintenance burden as you noted.

I’m just saying sometimes having a head at the top of the source often is a very useful way of conveying information, in some cases it may be the ONLY way or the easiest way.

goob April 3, 2010 at 16:53

I use TODO lists as a way to remind me of little tasks that aren’t important to the final outcome of the project, but are nice-to-haves. When written using @ notation most IDEs will recognise them and build your todo list automatically. So when I’m coding, but would like to come back some rainy day and rewrite a method using recursion instead of iteratively, I can simply write
@TODO – rewrite using recursion

And on occasion, I just look at my automatically generated TODO list for stuff, well, to do!

anon April 4, 2010 at 05:58

IMO, the Berne convention is a tragedy, and copyright law should be outright abolished. The thing to do with software is to “license” it as CC0, which effectively does whatever possible to remove copyright so that your work belongs in the public domain.

http://creativecommons.org/about/cc0

Marcus April 4, 2010 at 10:07

It’s useless, but some parts, like list of authors, that’s a pretty nice little dose of humanity to keep around, at least if the authors feel like it. I usually do, but then again I’m one of the few people who appreciates “john doe woz ‘ere” style graffiti”

JeanHuguesRobert April 4, 2010 at 11:15

I know a good reason why one may want to put a license in each file. It is when the license is the VanityLicense (that I created out of pure vanity).
—–
(C) Copyright Virteal Jean Hugues Robert. http://virteal.com/VanityLicense
Vanity License: You may take the money but I keep the glory.
—–

;-)

Al Brown April 4, 2010 at 11:28

the monkeys explain so many things going on its not even funny

electro-dude April 4, 2010 at 15:28

As a self-defence measure, I use the hide-show mode of emacs to reduce these monstrosities to a single line on my display, which I can then ignore more easily.

Screaming Monkey April 4, 2010 at 16:02

This was true only after 1989? I thought (uninformedly,) that copyright was implicit, if not from the beginning, then at least since much earlier than 1989.

Joel Parker Henderson April 4, 2010 at 17:18

> Often, source code files repeat the file name in the file itself.
> I’ve never seen the point in that.

It’s for older email systems. When you send a file via email, some attachment software may alter the filename or may inline the source code, thus not preserving the file name.

When you receive a file like this, the source code makes it easy to see the intended file name.

Hope this helps!

Read the bloody license! April 4, 2010 at 18:13

Maybe you should actually read some opensource licenses before you go off spouting ignorant ideas like this? Many of them require inclusion into the files themselves. Even worse, your haphazard methods of copyright assignment means it is harder to share code between projects and attribution will lost and thus license violations will increase.

Your recommendation is ill informed and totally irresponsible.

Ville Laurikari April 4, 2010 at 20:56

I’m (painfully) aware that many licenses, GPL and LGPL in particular, require large chunks of legalese in every single file. I’d much rather put one or two lines referring to a URL of the license or a separate file.

Obviously, you must abide by the rules of the license you choose to use, I choose to use licenses which don’t require a lot of boiler plate yadda-yadda in my files, if possible.

Ville Laurikari April 4, 2010 at 21:00

Joel, ah, email. The source of so many evil things in our lives :)

I did stumble upon a different explanation as well. Many editors and tools don’t include the file name when you print a file. So including the file name is a way to work around that particular limitation in your tools.

Ville Laurikari April 4, 2010 at 21:06

Screaming Monkey, 1989 is the year the United States became a party to the Berne Convention. Before that, AFAIK, the US copyright law required a mandatory copyright notice. In practice, this forced most software authors to include copyright notices, even in countries already in the Berne Convention, to avoid problems in the US.

Ville Laurikari April 4, 2010 at 21:07

@Commenter, thanks. IMHO, it starts to hurt when the boiler plate legal text exceeds a couple of lines. I prefer to simply refer to a separate file with the full license text. It takes a line or two and isn’t in my face as much. I can actually see some code without scrolling down after opening a file in Emacs :)

Tuomas Pelkonen April 5, 2010 at 19:50

Good points, however, in some organizations the version control system might have changed a few times and the history been erased. If the version control system is not used perfectly, it’s nice to know who is the original author of the code (so I know who to blame ;) )

For me, the biggest reason to use a small template is to make the code look more professional. I know it sounds funny, but if the code starts from line 1, it looks naked and somehow a hack to me.

Yami no Gakusei May 11, 2010 at 15:22

Thank you for the post. Just recentrly I had almost the same thoughts ;)

Matt Berridge May 11, 2010 at 15:23

I agree. The copyright doesn’t stand so all the legal spiel is pointless. You may as well just write “By all means look, but please don’t steal this code”

Things like versions, TODO’s, descriptions etc etc. – who cares. These are YOUR business as the developer, not the user’s. It is not their problem – you’re passing off the convenience of having them there for YOU onto the user in terms of file size.

Code comments like that are similar a Captcha in that respect. Spam emails sent to you aren’t the user’s problem so why make it theirs by having to fill in a stupid box.

Deal with it yourself, keep your comments in a text file or whatever – don’t push them on the user.

Patrick May 11, 2010 at 15:26

The copyright notice may not be legally necessary or meaningful, but it does act as a deterrent to some people. It says that you don’t want them copying the code as-is. Many people will respect this. So, I think it has psychological weight, if not legal weight.

Ville Laurikari May 11, 2010 at 15:34

Patrick, thanks for your comment. You point out possibly the strongest reason to keep some kind of copyright notice in the header. Even so, a one or two line summary of the license, not a boiler plate copyright text, would carry more information to someone who is pondering whether they can use the code or not.

Michael Becker May 11, 2010 at 23:18

Agreed that all that jargon isn’t usually necessary, however for agencies of different sizes, I’ve found that putting in information about “who worked on what, and when” is indispensable when you are tasked with updating a legacy file. You can then track down the original programmer (hopefully!) and save yourself hours of sifting through undocumented code.

Ville Laurikari May 12, 2010 at 10:41

Thanks Michael. I completely agree that it’s important to be able to see who has changed what and why. Especially the why. In my experience, this is best done with a version control tool. In a long winding project (the history in parts of our codebase starts from 1996) any comments regarding authorship or changes within the file become just too outdated, too terse, too imprecise, and too plentiful to be really useful.

{ 5 trackbacks }

Additional comments powered by BackType

Previous post:

Next post: