TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Re: Documenting Code/Why Is It So Ugly? From:Chris Hamilton <caxdj -at- EARTHLINK -dot- NET> Date:Tue, 2 Mar 1999 14:45:01 -0500
Rebecca Merck wrote:
> 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.
While this might be true, code samples are more valuable if they are
readable. And, in my experience, programmers (myself included when I was
one) are kind of anal about this. It's kind of hard to maintain code you
have to struggle to read.
> 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.
Again, I respectfully disagree. There are spacing conventions that make
life a lot easier for the people reading the code. For instance, C can
compile both of these statements just as easily, but which would you
like to work with? (Pretend it's written in a monospaced font)