Programmer Writing Style – Code and Shell Examples


Command-line specific recommendations

Do render variables in a command-line in a separate color/style

To alert users that part of a command-line is meant to be replaced by a value (such as your system username), make it clear where those exist in the command.

This is frequently done by rendering such variables :red:`red` and italic. It's good to use both, since you're using both shape and color to differentiate the replacement value.

Don't add a command-prompt to shell examples

This may have had a purpose in the past: to distinguish between running a command as a normal user ($) and as super-user (#) on POSIX shells. Furthermore, when documentation was mostly published in print, cut-pasting of code examples wasn't something you'd expect a reader to do.

Today this practice is mostly a nuisance. Adding the prompt to a command-line example means that your readers can't just triple-click to select an entire line for pasting. Since the advent of the sudo program, modern Linux/Unix/macOS use is to never enter commands as superuser anyway, but to route such requests through sudo.

So leave it off, your readers will thank you.