|
By Mike Gunderloy If you're writing computer books or articles, you're most likely including source code. Here are a few things to think about when you're crafting code for publication. Before you do anything else, you need to understand the formatting rules for the publication:
Line length issues probably cause more rework in galley proofs than anything else. If the publisher tells you 55-character lines, believe them; the 56th character will wrap around to the next line. This will at best look stupid and at worst confuse your readers. If at all possible, use your language's own rules for formatting logical lines of code across multiple physical lines, inserting line-continuation characters (if they're used) as needed. If you are stuck with something that just can't be wrapped in the context of the language, most publishers have a special typographical line-continuation character you can put in to make it clear that the wrapping isn't your fault; ask your editor about this when you need it. In some cases, short code samples go directly into the text ("snippets"), while longer ones are set off separately ("listings"). If your publisher uses this format, they probably have some number of lines (10 or 20, for example) where they like to make something a listing rather than a snippet. If the publication does use listings, you most likely are required to provide a caption ("Listing 6. Framboozling the Linterator using C++") for each one. For the most part, I recommend keeping code samples as concise as possible. The old joke about carving a statue of an elephant ("Just get a big block of marble and cut away everything that doesn't look like an elephant") applies here. You generally don't want to put in bulletproof error trapping, logging, or caching performance optimizations into sample code. Rather, each sample should demonstrate the point that you're discussing in the text at that point as parsimoniously as possible. You probably should stick a note in the introduction warning readers that the sample code isn't production-quality if you take this approach. However, if the point of your book is to demonstrate a production application, or to talk about performance, you can't get away with this shortcut. Sample code does need comments, even if it's explained in the immediately adjoining text. That's because some people will only read the samples, or only look at the code download. Sample code should also be formatted accoding to the generally-accepted standard for the language you're using. Even if you use a nonstandard format in your own work, don't try to impose it on readers -- unless you're willing to explain why you choose that format, and put up with upset readers anyhow. One exception to this rule is that you might want to lower the number of spaces per tab to three or even two if you work with deeply-nested code and a limited line width. By the way, you'll almost certainly have to replace tabs with spaces if you want your code to come out right when the typesetting process is done with it. Mike Gunderloy is the lead developer for Larkware and author of numerous books and articles on programming topics. |