"Jim Holsenback" <jho### [at] hotmailcom> wrote:
> Am I picking nits to be pointing this out?

Let's put it this way:

- This is a matter of coding style.

- Coding style doesn't really matter.

- However, *Consistency* of coding style *does* matter.

Reading code is easiest if you are used to the coding style it uses.
Reading code with a particular style helps you get used to it.
Therefore, reading code with a consistent coding style is always easier than
reading code with inconsistent style.

For example, consider the following code (using C here):

for (i = 0; i < n; i ++)
    {
    if (i % 2 == 0)
        {
        ...
        }
    foo (i);
    }

for (i = 0; i < n; i ++)
{
    if (i % 2 == 0)
    {
        ...
    }
    foo (i);
}

for (i = 0; i < n; i ++) {
    if (i % 2 == 0) {
        ...
    }
    foo (i);
}

for (i = 0; i < n; i ++) {
    if (i % 2 == 0) {
        ....
        }
    foo (i);
    }

There's no problem finding the closing braces for any of these statements even
across large blocks of code - once you know the pattern. But woe if you
intermix them!

for (i = 0; i < n; i ++)
    {
    if (i % 2 == 0) {
        ....
    }
    foo (i);
    }

Uh, yeah - perfect...

Even if they're never mixed in the same function, you'll still have problems
reading functions fluently if there is not a consistent pattern across the
whole code, or at least within a module.

The bottom line is this:

If you have the time, feel encouraged to "streamline" the coding style used
throughout the documentation. Don't worry which particular one is best -
because the best one is the consistent one.

If you have *plenty* of time, write some coding style guideline for the
documentation, so that future contributors can easily adapt their code to it.

If you have an *abundance* of time, put some thought into every aspect of that
coding style, trying to figure out which variant is best.

Whatever you do - be warned that some people *will* criticize the particular
coding style you choose, whatever that may be (even if - or maybe especially if
- you come up with a detailed rationale why you choose it), but be assured that
whatever style you go for is probably a good choice. I've never come across any
coding style that didn't have any drawbacks at all, so just go with whatever you
personally like best.

After all, you're the one taking up the task of "consistifying" the doc code
samples, so why the heck shouldn't the style reflect *your* personal
preferences?!

Of course you'll probably want to ask Chris Cason about this, as it would be
prudent to use the same coding style as in the code snippets provided by the
Windows GUI, the standad include files, and the sample scene files - but I'd
expect the answer to be thanks for volunteering to streamline *all* of these to
whatever style you deem fit ;)

Post a reply to this message