Best practice for writing useful software
Here's what I consider most important for writing programs that save their
users time rather than wasting it. A few of the points are Linux/UNIX specific
but most are not.
Good utility programs:
- Be aware of the outside world. Do not duplicate functionality that other
programs can provide together with yours. Be interoperable, use open
- Your program may be run by another program rather than a human, so be
tolerant to unusual and pathological input.
- Do not integrate a GUI unless your functionality requires it. GUIs consume
human time, text-based interfaces allow automation. GUIs can cause
dependency hell. GUI front-ends separated by documented interfaces are best.
- Use plain text files with explanatory comments for configuration. XML is
harder to read for both humans and programs, and is only needed for
arbitrarily deep tree structures.
- Include test programs in the distribution if you have them. They can help diagnose problems.
- Include a manual page. It's time-consuming to find out which of the other
documentation formats you favoured.
- Explain all acronyms and technical terms that may be unfamiliar to new
users, foreigners, non-native speakers and people with a different
- One does not read documentation through sequentially in full, so repeat
points that touch multiple issues.
- When referring to something verbally, insert hyperlinks (or page/section
references if the document format does not support them).
- Self-referential explanations ("fooblarg - blargs the foo") are useless.
- It's OK to deprecate something. But if you don't document its replacement,
don't expect users to switch.
- If specifying the behaviour of your program involves many nested
conditionals, consider modifying the program.
Good error diagnostics:
- Provide information about the specific occurrence of the error, not just the type of error.
- Describe what went wrong at the level at which the user interacts with the program, not in terms of program internals.
- Try to educate the user on how to avoid similar errors in the future, by pointing out what she did wrong and by referencing documentation.
- Diagnostic algorithms belong in the program, not in the documentation.