RE: Boxes for Code: Summary

Subject: RE: Boxes for Code: Summary
From: KMcLauchlan -at- chrysalis-its -dot- com
To: janice -dot- gelb -at- eng -dot- sun -dot- com, techwr-l -at- lists -dot- raycomm -dot- com
Date: Thu, 18 May 2000 13:20:47 -0400

Janice G. said:
> I got ten responses, and only two people said they
> are still using boxes around code examples, and
> that using a monospace font (generally Courier,
> which we also use), especially combined with an
> indent, was enough. Most people said that use of
> boxes was old fashioned.


I still haven't landed on a method I like.

I use boxes for command-line interactions. We still
have tools that use character-based menus... not
much GUI happening yet... mostly in-house tools,
slightly fixed-up for our toolkit customers to use.

I use Courier 9pt among 11-point body text, for
code examples.

Problem is, most programmers see code in programmer's
editors, spread wider than my margins can handle.
So, that's how they write it, too. Their editors
usually have default tab settings that just won't
fit on my printed pages.
I don't like to go really tiny on the Courier, to
make the samples fit. Sometimes I re-format, chop
spaces out of tabs, etc., but that's very tedious
and often doesn't work. I'll have a three-page
code sample and set it up so that all the lines fit
without inappropriate wrapping... and then, on the
third page I'll discover the programmer used an
extra-long variable-name that blows my careful scheme
out of the water.

I literally cannot remember even a two-line sample
from the past two years that could fit in my 3-3/4 inch
text area WITH an additional indent. I guess other
folks must use wide pages if they can consistently use
an indent from the body-text margin as one of the
formatting signals for code-sample text.

When wrapping is unavoidable, what do you folks use
as your standard for how a line of code should break?
After the break, how far do you indent? The programmer
uses an editor that auto-indents depending on which
field (and maybe what type of structure) he was in,
and has rules about how a line of code is permitted to
break. Certainly nesting can use up a lot of page
real-estate in a hurry.
I seem to be constantly battling to reconcile
space considerations with readablity. My page layout
-- which works fine in other respects -- is usually a
right-hand main-text column with a left-hand side-head
area. Too often, I give in and let a code sample
spread from margin to margin (i.e., not respecting the
column/side-head layout), and that's when a box of
some sort becomes attractive.

I've looked at commercial work, and the samples often
seem to be suspiciously ... well... sanitized for
presentation on a printed page. Hardly anybody uses
a statement with eight or ten arguments, stretching
clear across the screen... twice. Usually, other
people's samples seem to fit neatly on a page, with
lots of lovely white-space all round. Looks nice, though. :-)


Previous by Author: Stalking the wiley tech writer
Next by Author: RE: Stalking the wiley tech writer
Previous by Thread: Boxes for Code: Summary
Next by Thread: RE: Boxes for Code: Summary

What this post helpful? Share it with friends and colleagues:

Sponsored Ads