Re: Documenting Code/Why Is It So Ugly?

[Rebecca Merck <Rebecca -dot- Merck -at- ONESOFT -dot- COM>]

The really great news is that for most programming languages, the
spacing is absolutely irrelevant.

You
could
put
one
word
on
a
line
and the compiler doesn't care.  You could put 1000 words on a single
line and the compiler doesn't care.

*NOTE*: Double-check this with your programmer before you go monkeying
with your copy of the code, just to be sure that it's true for their
language.

So you can usually use your discretion in terms of where to break the
lines of code, and how to indent and space around broken lines, to make
it clear that they go together.  Just as long as you don't make a change
that renders the code uncompilable, you should be fine.

ABSOLUTELY I agree with Ben on font choice:  use a monospace font.  Very
important to the programmers.  They're accustomed to seeing code in
courier, and it's confusing to them to get a proportional font.  Mine
nearly strangled me when I suggested a font change.  However, in a book
where the standard text is a serifed font, to have the code in another
serifed font looks funny.  I downloaded Andale Mono from the Microsoft
site -- it's a sans serif monospace font, and it's what I'm using for
our code examples, since we use Garamond for the standard body text.  It
looks really good, and our programmers were happy with it.

Another thing I've been doing is to put a grey background behind the
code, to really set it apart.

Ben, btw -- I printed out the reference to your book, and I can't wait
to take a look at it!

-Rebecca


 From ??? -at- ??? Sun Jan 00 00:00:00 0000=