Re: Documenting Code/Why Is It So Ugly?

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)

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=



Previous by Author: Re: Developer Documentation
Next by Author: Re: The humor problem
Previous by Thread: Re: Documenting Code/Why Is It So Ugly?
Next by Thread: Re: Documenting Code/Why Is It So Ugly?


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


Sponsored Ads