So there I was, finishing up another man page for my little C code glue library ‘peak’, thinking of how neat writing man pages can be. Along the way, I have picked up a few interesting concepts and insights that can really help with code quality (and the man pages therein). Here they are.
Everything Deserves a Man Page
I remember watching Bob Ross telling us that “Everybody deserves a friend,” and he was right. Even the shortest and most obvious file should have a man page, whether you think it’s necessary or not. State your case. Write things down away from the compiler. This had the following effects on me:
- Interface and functionality awareness. Is it clear enough? Does the name reflect what it does? Is it really optimal? Is there something that can be done to improve it?
- Keep things simple. There’s no use for complicated APIs if you can’t break down what they do in one or two sentences.
- Focus efforts. Create the man page before you create your source files. Write down what you want to achieve.
- Check and track progress. Update the man page often. Don’t start being sloppy. It will affect your code modifications as well. If you don’t have time to update the man page you are probably afraid that what you did is stupid. ;)
Man Pages in the Repository
Share man pages with your colleagues. Make the history visible to the world. This adds the following benefits:
- Keep everyone informed. I guess this seems redundant, but consider someone drops a few hundred lines of code into a source file you are not familiar with. The update in the man page (if it was edited as well) gives you a quick overview of what has been done away from the restrictive length of a commit message.
- Give new employees a chance to catch up more quickly.
- Don’t waste your precious time explaining things to others.
- Give others a chance for review away from the code itself.
- Your boss and colleagues will (most likely) be happier with you.
- Give everyone the feeling that man pages are fun. People will catch on to that. Product quality is going to improve!
Consistent Writing Style
Interpreting the macro style in the raw man pages does not come naturally, but in time you will be able to edit them without leaving your favourite text editor. Here are tips to become a pro:
- Read the mdoc(7) page. Look for more input on the topic on the Internet.
- Start reading commits from BSD projects. As an example, developers on OpenBSD treat their man pages very well. You’ll pick up things along the way that you missed earlier.
- Keep under 80 characters, and break the line at the end of a sentence. That’s something I missed for a while. Adhering to this rule makes diffing easier on the eyes for everybody.
- Skim available man pages on your system. If there’s a layout that you like go to the source file and find out how it’s done. Then simply use it in your own man pages.
- Before you commit a change, look at the rendered man page. You want others to do the same.
- KEEP WRITING YOUR OWN MAN PAGES, EVEN IF NOBODY WILL EVER SEE THEM.
- Last but not least: Remember to always have fun!