Misc. convention stuff

["Bjarke Hammersholt Roune" <asmild@post6.tele.dk>]

>First off - the coding standard thing is on my TODO list now - but it's not
>the top item (the website for example is far more important now). So things
>will develop slowly here.
>
>Ok, some stricter conventions for internals are good. We'll see how strict
>(-> later).
>
Fine with me, it just needs to be done at some time. I would recommend doing
it withind a month or two or something like that, because the more code that
is done without the coding convention, the more code will have to be
retouched.


>>In the second part, I write about the numerous benefits of using a coding
>>convention, and why these benefits are not just something I'm making up
>>because I think it's a cool idea:
>>
>Ok, that's clear. We just seem to disagree on how far this convention
>should go.
>
Yes, that would seem to be the case.

There is a concept called "the point of diminishing returns" (you probably
already know about it). It was originally used in economics, but it applies
to much anything really. We seem to disagree on where this point is.

>>I think there are are more arguments in my origional mail, but I can't
>>remember all of them.
>>
>You could reread it ;-)
>(sorry ;)
>
lol :)

Ok, it was perhaps a bit on the longish side. Quite alot, perhaps :)

>>implementation is done, and more than acceptably inconsistent in API
itself
>>
>That's the point I'm primarily interested in - API inconsistency that can
>be corrected by coding standards.
>
Yes, that is probably where the returns of a coding standard would be the
greatest. I would recommend not putting this off for too long.

>There's also API inconsistency in terms of design, mainly as a result of
>the fact that the different parts are largely independent, but I don't know
>yet how to overcome that (and whether it is neccessary). -> later.
>
If this is an issue that is to ever be resolved, then it would have to be
resolved before too much code has gone from design to code, as this is by
definition a design issue. It would also be possible to resolve at a later
point, but that could easily get very messy, forcing the breaking and
recoding of a lot code if we are unlucky.

If this issue really *needs* to be resolved is another question. There is
the point that as the various PenguinPlay sub-projects deal with totally
different problems and gives completely different functionality to the
client, that they will naturally also have completely different designs.

I think that is a good argument, however, there are some issues that could
(and should) be resolved in this area. An example could be how to handle and
manipulate strings. I remember seeing somebody using the standard library
string class somewhere. Wheter or not to use that class is certainly a thing
that could be agree upon. Also, I think it would be wise agree upon which
container classes that are to be used (std lib?), and when to use references
and when to use pointers, or indeed to use references at all.

IMHO, these are important issues that needs to be sorted ASAP. Though
putting it off a week or two or three won't make everything crash and burn,
correct, putting it off for *too* long might not be the best course of
action.

>>I seem to remember the webpage saying something else somewhere (?).
>
>contact.html, right?
>
I can't remember... Sorry...

>In general - don't trust the website until it will have been rebuilt from
>scratch.
>
Have anybody ever discussed eactly what we want the website to be in
relation to PenginPlay? What we want to *accomplish* with it? What is the
goal? As an example, I IMHO don't think it would be a good idea to make
PenguinPlay look *too* phenomenal if we don't have anything working to show
people...

If somebody have discussed this, I would strongly suggest this someone write
it down somewhere (my apologies if somebody actually already has and I'm
just being ignorant).

>Ok. good point. Possible solution (more or less the current implicit
>convention): The primary header of each Part (subpart), i.e.
>Penguin2D.h, PenguinFile.h, ...  - no pp prefix (The Penguin... is enough
>and it's clearer).
>All others: pp<partletter> prefix (i.e. "ppf" for PenguinFile, "ppg" for
>PenguinGraphics, "pps" for PenguinSound).

I think that's a good idea.

btw, are there projects with a prefix longer than 1 character?


>>Notice how Adrian here makes spaces inside his if's.
>>
>>Christian Reiniger:        if (some expression)
>>Adrian Ratnapala:         if ( some expression )
>>
>There's no problem with having both forms - even intermixed. Both are
>readable, both are "consistent" in themselves (i.e. there's either no space
>around the expression or one space at each side of it).
>
A single character is also consistent in themselves: ie, it is exactly the
same nomatter how you look at it, and it's the same all over. Very
consistent. :)

>Don't make things consistent for the sake of consistency alone. The goal is
>readability, and readability is not harmed by this.
>
If you look at something consciously, no, this doesn't really matter.
However, if you want to just skim a page and be able to unconsciously parse
everything and thereby know what the functions does, this matters somewhat.
Some might object to my use of the word "unconsciously" here, but my point
is that any inconsistency makes things slower to read: the less the brain
has to deal with, the faster it will come up with results.

There is also the matter of  completely consistent code infer a certain feel
of familiarity with the code, even in readers that haven't read very much of
it. This effect is very much equal to the effect that big companies spend
extreme amounts of money on comersials to get. Read the appendix at the end
of this Email for more detailed info on this.


>Again - the goal is readability. I often mix these forms, depending on
>what's more readable in the specific situation.
>For example, this:
>
>-----
>int x = strcmp (String1, String2);
>
>if      (x > 0) return String1;
>else if (x < 0) return String2;
>else            return 0;
>------
>
You find this easy to read? I find it to be very alien to anything I've ever
seen, thus I don't find it easy to read.


>is certainly more readable (through the tabular  "if <-> then" look and
>because the parts are not as close to each other) than this:
>
>-----
>int x = strcmp (String1, String2);
>
>if      (x > 0)
>        return String1;
>else if (x < 0)
>        return String2;
>else
>        return 0;
>-----


I find this very easy to read, much more so than your previous example. This
is because this is what I'm used to, which is why I think even suchs things
should be standardised (read the appendix for more info). Not nessecarily to
say that my way of doing it is right and your way is wrong. The point is
that I would only have to get used to having it ONE way when reading
PenguinPlay code.

>and this (where the reader almost gets lost in the spacing):
>
>-----
>int x = strcmp (String1, String2);
>
>if      (x > 0)
>{
>        return String1;
>}
>else if (x < 0)
>{
>        return String2;
>}
>else
>{
>        return 0;
>}
>-----

>
This is not easy to read for me, as I'm used to having 1 statement
conditional statements suchs as these be not enclosed in braces.

>>ppgColourMode& ppgIndexedMode::Clone()const
>>{
>> return *new ppgIndexedMode(*this);
>>}
>>
>>Here, the const is places directly after the "Clone()" : no space. I
>>haven't
>>actually looked for this in other places, but if *I* had coded this, there
>>would have been a space, so I would have been inconsistent with him.
>>
>Sorry, that's nitpicking.
>
It sure is. It is also unintuitive. Refer to the appendix for why I think
even so small things suchs as this is important.

>>*** -->>> "pcburns" ? (ppsSampleRaw.cpp) <<<-- ***
>>
>>notice the use of the file type ".cpp". This is not used by anyone else
>
>Correct. Peter, Derek, can you stick to the ".cc" we use? Not urgent, but
>you know... Also ".h" for headers.
>BTW using something other than ".cc" or ".C" for C++ sources effectively
>disables some of make's mechanisms (automatically compiling all sources of
>known type).
>
This is somewhat annoying to me, as I have to rename all the .cc files when
I use them, and then rename them back again. MS VC++ will not parse .cc
files for automatic recognision of classes and functions. It will compile
.cc, but I have to manually set this as an option for each and every .cc
file. But I guess if there are most people using .cc, I better do that
too... :(

>>ppsSampleRaw::~ppsSampleRaw()
>>{
>>    delete [] m_data0;
>>    m_data0 = 0;
>>    delete [] m_data1;
>>    m_data1 = 0;
>>}
>>
>>here, all members that are deleted are also set to 0 (delete should
already
>>have done this, btw), even in the constructor. This is not done by
>
>According to my docs delete isn't required to set the pointer to 0.
>

What I mean was that, atleast in debug builds, delete should, besides
deleting the pointed to memory, also have set the pointer to 0.

>>variables are prefixed with "m_". To declare a pointer type, the * is
>>placed
>>together with the rest of the type specifies, like so:
>>
>>char* string
>>
>>rather than:
>>
>>char *string
>>
>That's misguiding, as the "*" binds to the respective variable, not the
>type.
>

I actually think it is a good idea, and do it myself. A pointer to a char is
not a pointer that just happends to be pointing to a char, as char * would
seem to indicate, it is rather a pointer to a char, and nothing else, as
char* indicates. Also, the fact that a variable is a pointer is quite
clearly part of its type, not its name, and should therefore be placed
together with any other type specifies rather than the name.

Declaring more than one variable on one line is misleading if any of the
declared variables are pointers:

char c1, c2, c3, *c4, c5, c6;


When you skim the line, you see that what's being declared here is of type
char, and that *is* the type of c1, c2, c3, c5 and c6. But c4 has different
type from the other variables, *despite* being declared *on* *the* *same*
*line*. It is therefore IMHO poor programming practice to declare more than
1 variable per line if any of the variables being declared are pointers,
thus making the only argument for putting the * together with the name
invalid.

Bjarne Stroustrup also practices this practice of putting the * where it
belongs as a type specifier.


***************************************************
****************** APPENDIX ******************
***************************************************

Look at the way Windows 98 is designed. If the "close window" button is 1
pixel down from the top of the window and 2 pixels left from the right side
of the window in one window, that's the way it's going to be in ALL windows.
You can trust that. You don't even need to look. The same is the case for
*everything* in Windows, as in any other user-friendly GUI: things are not
just kind of the same, they are *EXACTLY* the same. Everything that is the
same
inbetween programs not only looks and works "somehow" the same, no, they
look and work *EXACTLY* the same.

This is not nessecary, speaking from a strict comprehensive point of
view: even if the "close window" button is off by a few pixels from program
to program, and even if it only looks kind of the same, people should be
able to comprehend that whatever button is somewhere around the top-right
corner of the window with a cross in it is the "close window" button.

However, then every time you wanted to close a window, you would have to
make a conscious effort to look in the top-rigth corner for something
resembling a cross and click it. The way it is now, you don't need to do
that, you just move the pointer up to where you *know* the close button will
be. Your eyes might follow the pointer out of habit, but I atleast
find I've begun pressing the mouse button before I look.

The "close window" button is a quite small button. None-the-less, I've just
succesfully pressed it with my eyes
closed 3 times in a row (positioning the mouse pointer in the middle of the
screen after each try, naturally).

I have before claimed that an API is an user interface. I will now claim
that code is also an user interface. All user interfaces follow a set of
universal rules (anything that comes to us by way of our senses is user
interfaces, really, as the senses themselves are user interfaces). One of
them is that any task we do alot of times, we will become more proficient at
and be able to gradually do faster and faster. Another is that if something
looks a specific way, and that something gives us a set of associations, we
will recall those associations when we again look at something that looks
that way, and anything we learned while looking at the original something
will be easier to remember when we again look at something that looks like
it.

Am I saying that have this kind of inconsistency:

if (some expression)
if ( some expression )

will make people unable to understand whatever this little piece of code was
part of? Most certainly not.

Am I saying that that kind of inconsistency will make people think less of
PenguinPlay? Not exactly.

Am I saying that that kind of inconsistency will make it harder for people
to understand the internal workings of PenguinPlay? Well, kind of, but not
exactly.

Am I saying that that kind of inconsistency will make it harder for people
to clearly distinguish PenguinPlay code from other people's code, and
therefore also make it harder to distinguish PenguinPlay as a whole clearly
from all the other programing projects going on, and, indeed, from
everything else in people's everyday life? Yes, that is exactly what I am
saying.

When a large company wants to sell something, they pay extremely large sums
of money to other companies that promise that they can give that company,
and it's products, some benefits that it's competitors does not posses
(everybody does this, so it more or less doesn't matter, though, except for
those that *DOESN'T* do it).

These benefits must be extremely profitable, or companies wouldn't pay so
much money to get them.

You have probably noticed that companies will try to get their name spoken
as many times as possible, their logo seen as many times as possible and
their sound (if they have one) heard as many times as possible.

The reason that this is so profitable for companies, like, say, Coca Cola,
is this: Inside everybody's head, there is a little area with a small sign
that says "Coca Cola" (well, not really, but there's something alot like
it). Now, the problem for Coca Cola is that the conscious attention for
the most part of the day is not aware of this little area. What Coca Cola
wants is to tie as strong a bond between this little "Coca Cola" area and
*anything* else inside the consumers head. Be that very large bricks,
clowns, balloons, forks, teaspoons, *whatever*. If Coca Cola can manage to
somehow associate another area of the brain with the Coca Cola area of the
brain and create a connection, then both areas grow larger, and, more
importantly, they both gain more and stronger connections. This means a
larger portion of the
consumers intellect is "tied up" in the "Coca Cola" area. This is cool for
Coca Cola because it makes the consumer buy more of their colas.

This, btw, is not bad for the consumer or something like that; it's the
natural way
the brain functions and learns; by adjusting the strength of connections
between the different "areas" (neurons, or collections of neurons).

However, the *best* thing for Coca Cola is if they can get some area of the
mind connected with the Coca Cola area with a very strong connection: I they
never ran their comersials more than once and changed their logo and sound
every other day, none of those things would get a very strong connection to
the Coca Cola area. Repetition is needed. Every time we see the Coca Cola
logo, hear their sound or see one of their comercials, the Coca Cola area
gets a little bit better connected with each of these, aswell as other areas
of the brain. This all help towards selling more of Coca Cola's colas, and
promote the image of Coca Cola, regardless of what that image actually is.

If you think about this, I think you'll see why I stress the point that even
small things is important in a coding convention, also if it seems like nit
picking, and even if it actually is. Especially if you consider that order,
neatness and effeciency will usually be very strongly connected with
consistency, as these words are A) often used in conjunction B) these words
mean almost, or nearly, the same.

What happends in a class room is somewhat the same: The teacher talks about
a subject, this subject gets it own little area in the brain. The subject
the teacher is talking about then becomes increasingly easier to understand,
remember and implement as the connections made with this area grows
stronger.

Imagine this scenario: (assuming the teacher's name is Richard)

The teacher walks in exactly the way he always does. He opens his worn
suitcase exactly the way he always does. He talks with the same boring voice
he always uses. He walks out again in exactly the way he always does.

What will this accomplish him? What will happen inside the brains of the
students? A) there will be made a little area inside their minds that will
say "Richard". This area will get *extremely* well connected to the rest of
the brain as they, day in and day out, have to put up with this teachers
extremely boring classes. Anything this teachers teaches will be strongly
connected to the person of this teacher.

What is learned is associated by the means that it is learned by. This will
make both areas in the brain, the area for what is learned, and for the
means, grow better and stronger connections.

How does this all apply to PenguinPlay coding conventions?

The code is the means, and the abstraction of the code is what is learned.
Even minute differences in the code will connect to *different* areas in the
brain.

That means that expressions of this type:

if (some expression)

and expressions of this type:

if ( some expression )

Will not be stored in the exact same area of the brain. Of course, as these
two kinds of expressions will usually be used in the same kind of contexts,
and they do share alot of common ground, the two areas in which they are
stored will have some kind of connection, but that is certainly not the
same.

This is very much like a computer program: the more the brain can assume,
the less situations it will have to deal with, the easier and faster it will
be to get the task done.

Only doing one of the above things in all code means that more conscious
resources are freed, so that you (the conscious you) can use your time
finding out what the code actually DOES, rather than finding out what each
line would mean for a compiler.