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 standards.
• 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. GUI front-ends separated by documented interfaces are best.
• Do not cause dependency hell by using a popular library if you need only a small fraction of its features. Try not to depend on any functionality you do not need.
• 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.

Good documentation:

• 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 background.
• 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 people to stop using it.
• 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.

TOS / Impressum