What is the best way to present source code, both offline and in books?

Question

Being somewhat typographically obsessed, I am curious: what is the best way to present code - both online and offline. In particular, I'm interested in:

• What kinds of typefaces and sizes work best online and offline? Is it better to use proportional fonts for code (e.g., like Stroustrup does in 'The C++ Programming Language')? Serif, sans-serif, or mixed?
• How should code be annotated - with the typical // comment markup, or perhaps just with a different typeface (and no comment tags)?
• Is it worth drawing arrows (or something similar) to show how different blocks of code relate to one another?
• Does showing code in several columns side-by-side work at all?
• Does anyone need things like line numbering, altering lines, etc.?

Answer 1

This doesn't exactly answer most of the questions, but you might be interested in reading up on Literate Programming. The gist of it is that you write your code and documentation in the same document, and it is formatted for web or print or whatever. And when I say documentation here, it's not usually one-line snippets of documentation, but whole paragraphs or pages describing what's going on in the program.

Answer 2

Well, let me add my vote against proportional fonts, as used by BS in TC++PL. It really drives me nuts! Similarly Soctt Meyers in Effective STL, with the added horror of some nasty hightlighting.

For me, the classic book on programming will always be K&R, as I don't think it has ever been improved on for clarity of presentation. so I would suggest copying it slavishly.

Answer 3

I like the use of an extended character-set when writing dummy code in text. The LaTeX fonts for code and math markup work well.

A good example would be using a left arrow for assignment or binding rather than =. The best examples of code in books I have seen has been things like the Dragon Book or TAOCP. I think a mixture of mathematical etymology due to the ability to render those characters and a relation to common syntax is great.

A mixture of the usual fixed-courier type fonts and advanced math markup available through Computer Modern in LaTeX I think works well for readers of a mathematical disposition ... and it can look very nice.

Answer 4

Just a couple of things that cross my mind:

• Limit the number of lines to a minimum
• Line numbers only when needed
• You can certainly use different fonts, but what about a different background? Like a light gray? Box your code and I think there is no problem in putting two boxes next to each other.
• Depends on the costs, but what about coloring certain elements - like most IDEs do -?
• Write working, real world code! Therefore I would suggest to use the normal // comment style and not just a different font.

Answer 5

• I would use a monopaced font like Consolas.
• Since comments usually appear as just a different color (at least in the IDEs i've seen), i'd leave them in as-is.
• What do you mean by "show how blocks relate to each other"? indicate where functions, if statements, etc. start and end? if so, it might be helpful; i honestly don't know.
• It might work if you were comparing a couple of chunks of code to indicate some subtle difference that would not work in one but work in another, but i don't see much use for it beyond that.
• Line numbers might help if you make references like "go to line XYZ in the previous code sample".