Re: Documenting Code/Why Is It So Ugly?

[Chris Hamilton <caxdj -at- EARTHLINK -dot- NET>]

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)

VOID_API setParm2ByteInt(THREAD_API aHandle,
STRING1B_API aFieldName, INT2B_API
anInt,
PINT2B_API status);

or

VOID_API get2ByteInt(THREAD_API     aHandle,
                     STRING1B_API   aFieldName,
                     INT2B_API      anInt,
                     PINT2B_API     status);

--
Chris Hamilton
Technical Writer
Tampa, FL
caxdj -at- earthlink -dot- net


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