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
// commentmarkup, 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.?
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.