Things not to do in an open-source project

After years of building packages for my box, I’ve encountered several very annoying tendencies. In no specific order:

1. From a library, don’t print output to stdout or stderr, or any other arbitrary file or stream. All error messages should be returned to the application which can then decide what to do with them. It’s also wrong to require an “error handler” to be established. The way that an error is handled often depends on the circumstances of the call to the function in which the error was detected. There’s nothing worse than application which spews out meaningless dribble from one or more of its libraries.

2. Not allow “make DESTDIR=/some/directory install” to alter the installation location.Using something other than DESTDIR should be avoided (it’s a de-facto standard) and if it’s not documented, that’s even worse. (INSTALL_PREFIX is sometimes used instead. Anything else is definitely out).

3. Use a funky build system which doesn’t allow “make DESTDIR=…” or equivalent. Makefiles are ugly but they can do the job. Most “better makes” are actually really crap.

4. Have an empty README, NEWS or INSTALL file. It is arguably better to have no file at all – at least then no-one will waste their time opening it in a viewer. Even better would be to have some real content. The README should at least say what the project is, what it does, and give a link to the website. NEWS should document changes between versions. INSTALL should say how to build the software, list any build and runtime dependencies including required version numbers, and say how to control where “make install” puts stuff (which should be by using DESTDIR, see above).

5. Use “-fno-strict-aliasing” as a compile option (to gcc). Needing this option means that your software is broken. The correct solution is to fix the software. Don’t type-pun pointers, and if you must, do it in a way that doesn’t violate the C99 standard.

6. Call your library a “C/C++” library if it is written in C. C++ libraries use C++ namespaces, and have classes. Otherwise it is a C library (which may also be usable from C++).

7. Neglect documentation. For a library, all the API should documented in separate documentation (not just in the header files). Documentation should be precise, verbose, and cross-referenced. In code, use comments. A block of code that is 10 lines or more and has no comment is a danger sign. If it is “patently obvious” what the code does from reading it, then summarize it in a comment – it will still be useful for those not familiar with the code (in other words, get a clue. It’s not “patently obvious” to anyone but you). Make sure to document the build system (specify what do variables in the Makefile do, if nothing else).

8. Write the program/library in some scripting language (or an obscure compiled language) and fail to mention the fact that the software is written in this language on the project web page.

9. Fail to do releases every now and then, if changes have been made. Don’t be in a position where you (or a dependent project) are recommending using sources from version control. Releases (with meaningful version numbers) provide a reference point, making it easier for your users to diagnose and solve problems, and for other projects to correctly list dependencies. (ffmpeg, I’m looking at you).

10. Have a dependency on a trivial little piss-ant library, and neglect to include said library in the tarball. Don’t force people to hunt down and separately compile another project wantonly. Your build system should use an external version if one exists, otherwise, it should build and link against the included one.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.