Better Headers

I review a lot of code and by extension read a lot of source code files. One of the things that drives me to distraction is trying to sort out what a specific bit of code is licensed. Now, I don’t care about GPL the way a lot of people do. When I’m reviewing plugins for WordPress.org, I only care in that a repository requirement is that all code in your plugin is GPLv2 (or later) compatible. If you’re not hosting on WordPress.org, I only care if I want to use your code and I need to see what the possible restrictions are.

While I’m mostly talking about JS files here, I wish people would remember to put in the right header information for all their code.

Headers I Hate

It absolutely kills me to see this as the header of a JS file:

/*! My Awesome JS - v1.0.0 - 2015-01-14
* http://example.com/myawesomejs/
* Copyright (c) 2015 John Doe */

Actually, what’s worse is this:

/*! My Awesome JS - v1.0.0 - 2015-01-14 */

This means I know nothing about your code license. If I have the URL, maybe I can be really lucky and go there, see a link to your full source code, download, open the zip, and maybe you put a license file in there. Most often, however, the answer to that is not. With a lot of newer projects, they link to Github, which is great since I can go and look for that LICENSE file. Github even prompts you about making one when you create a project. Love ’em

Realistically, if you’re releasing code for the world to use then you’ve got to license it. Even if you don’t care about licenses, putting a public-domain clause on your code means it’s free for all nations to use is so easy a caveman could do it.

Headers I Love

Okay, so if you’re making your own JS, what do I think your header should look like?

/**!
 * My Awesome JS v1.0.0
 *
 * @copyright Copyright 2015 John Doe
 * @author    John Doe
 * @link      http://example.com/myawesomejs/
 *            http://github.com/johndoe/myawesomejs/
 *
 * @license   Use permitted under terms of CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
 *            https://creativecommons.org/publicdomain/zero/1.0/
 *            http://example.com/myawesomejs#license
 */

That’s it. Obviously that’s the non-minified version. If I wanted a minified version it would be this:

/*! My Awesome JS v1.0.0 | (c) 2015 John Doe | example.com/myawesomejs#license */

There’s an argument to be made about minification and how I shouldn’t have any headers in order to compress the code to the extreme, but let me show you the jQuery minified file’s header:

/*! jQuery v2.1.3 | (c) 2005, 2014 jQuery Foundation, Inc. | jquery.org/license */

It covers your license and your copyright information there in one go. It protects your interests and makes it plain for everyone to see what’s going on, how to get in touch with you for changes, and all sorts of awesome open-source things.

Picking a license…

In the above example, I picked CC0 for a reason.

That’s the ‘unlicense’ I think you should be using if you’re releasing code to the world and don’t want to be bothered by the hassles of any informal sort of license. Sadly, not declaring a real license can cause problems outside the United States. Here, we would interpret the license based on what the author intends, which is already a bit of a dangerous idea, and presume a license means exactly what it says, which makes them non-copyleft free software licenses and compatible with most other free software licenses. It may make it outright incompatible with commercial software. And worse, other countries have stringent views on the copyright aspects of these licenses.

Now that said, my other favorite ‘For god’s sake, just take my code’ license is the WTFPL license.

For me, if I want to release code that really is free and can and will be used by anyone, I pick the CC0 or WTFPL. It covers this for everyone, as far as I’ve been able to tell, even commercial.

The GNU have their own license recommendations of course, and Jeff Atwood has a good post about picking a license that explains how most of us feel about the headache. Of course, if you’re forking someone else’s code or building on their work, check the license they used to make sure you don’t violate it with your new license. Not all licenses are ‘backwards compatible.’

Ipstenu (Mika Epstein)

I’m Mika (aka Ipstenu) and I’m complicated. I’ve been on the net since the days of dedicated terminals and Novation CAT modems and solved Missionaries and Cannibals (or Goats and Cabbages) before I was six, and blog about WordPress and technical/computer things at Half Elf on Tech.

See Full Bio