Matt Gemmell

Raw Materials book cover image

My book Raw Materials is out now!

A collection of personal essays, with exclusive content and author's notes.

» Find out more

Open Source Code

6 min read

As developers, most of us will release some open source code at some point. I’ve released quite a bit of Mac and iOS source code over the years, and I’ve used or referred to the code of countless others.

I strongly encourage releasing reusable portions of your code - it’s the lifeblood of the developer community. Over the years, I’ve put together a set of best practices for releasing open source code, to make life easier partly for yourself but mainly for those who will use your code.

## Speak the language

Programming languages don’t exist in a vacuum. Most languages are associated with a specific platform and toolkit, but even multi-platform languages are bound by conventions unique to them. Being aware, and respectful of these conventions is a requirement for releasing your code.

You can’t just release any old thing. To be useful to other developers, it has to follow the standard patterns, naming schemes, expected behaviour and configurability of their standard toolkit. If your code isn’t at home on its platform, please don’t release it - instead, spend more time learning the conventions and then release something that follows them.

This is particularly true of understandably enthusiastic recent converts to a platform, eager to make a mark on a new community and share their new knowledge. I completely understand that drive, and it’s admirable. But what the community actually needs is code that will be instantly at home in a piece of software on that platform, not something that smells vaguely like something entirely different.

We’ve all seen code that uses, say, Java-like conventions but is written in Objective-C (for example, making heavy use of exceptions for error control flow). It’s like speaking broken French in a British accent; you think they’ll appreciate your effort, but really they wish you’d just go away.

Name methods as they’re named in the standard toolkit. Obey conventions about indicating (explicitly or implicitly) what’s public and what’s intended to be private. Use the parlance of the platform, particularly in documentation where the compiler won’t alert you (an “interface” is a very different thing in Objective-C than it is in Java).

Make the code at home on the platform, or keep it to yourself. Be respectful of local customs, or go home.

Make it reusable

There are appropriate places for snippets (chunks of code, often trivial, to paste into your own methods or functions, which aren’t reusable in the traditional sense), but don’t release them separately.

If your IDE or editor supports exportable libraries of snippets, put them there, or answer a question on Stack Overflow. Generally, the most useful open source code starts at reusable components like classes or libraries, and goes all the way up to entire apps or frameworks.

Document realistically

Decide whether you’re going to provide separate documentation for your code and keep it up to date. If you can’t promise that, then don’t provide separate documentation.

In either case, provide brief explanatory documentation in comments for salient public properties and methods, particularly initialisers and commonly-used functionality, and explain any particularly obscure code where necessary. A big-picture block-comment at the top of a header file outlining what a particular class is used for is always handy, with a link to your site or repository for more information.

Try to consider the getting-started case too. If there’s something non-obvious about getting your code up and running in a new app, that’s clearly worth special mention (and perhaps a redesign before release, if possible).

Include a Read Me

Your Read Me file should be plain text; don’t be an idiot and use RTF or some horrible format that isn’t immediately readable in the repository, on the command line, and in a modern graphical file browser without launching any dedicated application. No, including a screenshot is not a valid reason to use a non-text format.

The minimum information you need is:

  • What the code does, broadly speaking. Skip the marketing; just describe its purpose.
  • The name of the author, with contact info if appropriate.
  • Where to get the latest version (your code will be redistributed as isolated, outdated files). Ideally, this will be a public repository with an issue-tracking system.
  • What the dependencies are, if any, including the versions you used.
  • What license it’s released under (see the License section below).
  • The minimum essential set of files people will need to copy into their own project to use the code. Almost everyone forgets to include this.

You might also want to include the following optional but helpful information:

  • A brief, readable feature summary so others can decide if it’s suitable for them.
  • Whether you offer support via email (I’d advise that you not do so - instead, point people to a suitable community site, and spend your time writing new code).
  • Any particularly interesting/thorny points or weirdnesses we have to know about.

Keep any long-form discussion out of the Read Me; people mostly don’t care about the back-story, and those who do will happily go elsewhere to read about it. Write a blog post, and link to it from the Read Me. You’ll also get more interest and reputation by doing it that way.

Include a demo harness

Don’t just release bare classes. Create a new, empty project for your chosen platform and build it into a demo of your code. There doesn’t need to be a checkbox to toggle every possible option; just show people what it can do, and how to use it in an app.

Keep the project loosely coupled to your code; don’t cheat. If you can’t make a demo harness without coupling it tightly to your code, your code isn’t sufficiently reusable and needs to be revised. Don’t waste other people’s time. The fact that you’re giving some code away doesn’t excuse you from professionalism.

Make sure that the demo code is very brief. If you require significant app demo code just to show how your reusable code works, you need to revisit your code and consider whether its default behaviour has been sensibly chosen, or whether you can add some low/zero-config convenience behaviour to get people up and running quickly.

Use a permissive license

Don’t use the GPL. The only reasonable scenario for the GPL is for an entire piece of software which must remain open for all time, to insure against data lock-in or premature hardware obsolescence. If you’re writing a printer driver or a codec, fine, you could consider the GPL. But in 99.9% of cases, avoid it like the plague.

The point of releasing code is to let people use it. Most people want to use it commercially, because that’s how the world works. Your code isn’t so special and wonderful that it couldn’t have been written by someone else. So, using the GPL is enforcing assholery on everyone because you think that someday, some other asshole might not make their code available in a time of dire social need. That’s crazy. It’s dealing on pure idealism and ignoring statistics and commercial reality.

Here’s the sequence of events when an inexperienced developer downloads some open source code that’s licensed under the GPL:

  1. Dev looks at the code, and realises it’s perfect.
  2. Dev tries integrating it into their app. Dev feels happy.
  3. Dev checks the license, and sees it’s the GPL. Dev feels sad.
  4. Dev either:
    • Throws your code away and finds a substitute,
    • Rewrites it themselves, or:
    • Uses the code in a commercial app anyway, hoping to not be found out.

The timeline for experienced developers is shorter, and also applies to all companies:

  1. Dev searches for code, and checks license before downloading.
  2. Dev sees it’s GPL, snorts with disgust, skips it and continues looking.

You’re kind of destroying the whole point of open source code if you use the GPL. So, ignore what the Software Unabomber says and use a sensible license.

Your license should:

  • Allow use, modified or unmodified, in binary (compiled) form.
  • Allow redistribution, unmodified, in source form.

Your license probably should:

  • Allow redistribution, modified, in source form (with clear documentation as to what was modified, and by whom).

Your license maybe should:

  • Impose whatever conditions or restrictions you prefer (commonly, attribution for yourself as the author).

Your license absolutely should NOT:

  • Require that apps using the code be themselves released as open source code.

If you’re in doubt, I’d say go with one of the BSD licenses or a more explicit attribution license. In some cases, companies who want to use your code won’t be able (or willing) to provide attribution in the resulting software, and will ask to be granted a custom license. That’s absolutely fine. I suggest making them pay for a non-attribution license, which is what I do on my code license store.

Use source control and issue-tracking

If you’re not using source control, even for your own personal projects, you’re not a developer - you’re a hobbyist or a tinkerer.

It doesn’t matter what your situation is. Get out of bed before noon, shower every morning, dress as if you’re leaving the house even if you aren’t, and generally have some self-respect. Professionals use source control, and you should aspire to be a professional.

Similarly, use an issue-tracking system. It doesn’t have to be fancy, but it does have to be more than your email app. Github provides one for you, there are dozens of free (and open source) implementations you can run on your own server or locally, and you can even make one yourself with whatever database package you’re familiar with. Just make sure you have one, and make sure you use it.

Conclusion

If you’re considering releasing some of your reusable code, that’s great. Do it in a way that maximises benefit while minimising difficulty, and you’ll have the best chance of receiving all due credit and reputation for your work.

If you enjoyed this article, you might also want to follow me on Twitter.