Re: Documenting Code/Why Is It So Ugly?

["Steven J. Owens" <puff -at- NETCOM -dot- COM>]

Smith, Martin writes:
> Note that some of the freely available/shareware text editors (such as
> TextPad) do a nice job of working with source code. They "understand"
> how the code is indented (using either spaces or tabs) and correctly
> handle the various character combinations used to break lines. The

     Some of them, for example Emacs C-mode, actually understand the
code syntactically and produce appropriate indentation.  This can be
quite handy when you're working on a program and inadvertantly leave
off a statement or block terminator (typically a semi-colon or a curly
brace - } - in C).  You press the tab key and the editor doesn't indent
the statement the way you expect it to, which indicates that you left
something out.

     To turn this around and relate it to tech writing, if you're
using a language that's supported by an editor with this capability
(for example, emacs has special modes for many languages, C, assembly,
fortran, etc) you can try using the editor to produce a consistent
indentation style.  This may not be the style your programmers prefer
- there are all sorts of holy wars over this sort of thing, analogous
to various writerly holy wars over writing style and nuances of layout
- but at least it'll be consistent.  Let the programmers dig up an
editor with the appropriate indentation style if they have a
preference.

     For example, in emacs I'd load C source in, do an indent-region,
then do a region untabify (which converts tabstops to the appropriate
number of spaces), save the code and load it into the DTP package in a
monospaced font.

Steven J. Owens
puff -at- netcom -dot- com


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