Re: [glob2-devel] coding guidlines

[Stephane Magnenat]

Hi everyone,

Please do not get it wrong. For me, cleaning the code is a very good idea
and indeed something that should result in attracting more developers. But
we have to clean the code in a sense that really helps people to
understand it. In particular, understanding a code is more a matter of
getting ideas of the structure and of the execution flow at a broad scale,
rather that having perfect tautological sentences in autodoc. We have to
take care, because perfect tautological sentences do give a false feeling
of clarity.

So you are welcome to go on with cleaning, but try to keep the
aforementioned warning in mind. When you cleanup a class, add a
description for it, put it in context with related classes (which may be
different that all classes it holds pointers to). Write descriptions of
logical modules (network engine, game engine, ...) rather then split them
into directories which would result in classes that are in wrong
directories anyway because they belong to the two modules. Of course,
libgag and USL can have their own directories, because they are separate
modules. But I would not split game and game gui for instance, but putting
the AI in subdirectories might be a good idea. In the same spirit, if
three small support classes (or one support and one main) do work closely
together, it would result in code easier to understand and maintain if
they are in the same file.

So in summary, use common sense, avoid hard rules, and think semantic
rather than syntactic.

Thank you :-)

Have a nice day,

Steph