Re: [Fresco-devel] Coding guidelines, again

[stuff deleted because of agreement...]

>  - Return type and function name on separate lines
>      void
>      foo(int bar)
>     rather than       
>      void foo(int bar)
> 
>    Justification: Return types in C++ can be pretty long; this reduces
>      wrapping and is easier to read to boot.

right, they *can* be rather long, so I would not mandate such a line break
but instead use the 78 characters-per-line rule to justify when and when not
to break between return type and function name.

Addition: line breaks after 'template <...>' in template functions/members.
Could be done always or if needed, I'm easy with both.

>      It also means that you can more easily grep for definitions.  Eg,
>      to find the definition of "foo", use:
>        grep -r '^foo(' .
>      If you want to include the type as well, use:
>        grep -r -B1 '^foo(' .
>      If you want to see all the function definitions in foo.cc, use:
>        grep -E '^[^[:space:]]+\(' foo.cc
>      and so on.

uhm, my editor generates a menu with all functions anyways, so
this is a non-issue (for me) :-)

>     If you have an initializer list, put the ':' after the closing ')'
>     of the parameter section and start a new line.  If the
>     initializers all fit on a single line, put them on a single line;
>     otherwise put each on a separate line.  [[FIXME: rewrite this
>     rule, and break it into multiple sub-rules]]
>     So:
>      class Foo
>      {
>          // Correct:
>          Foo() :
>              my_bar(0), my_baz(0)
>              {}

I'v never seen this before, I always do

Foo()
   : my_bar(0),
     my_baz(0)
{}

dunno, whether one or the other is more (self)consistent, just a
matter of habit, I guess.


>     Constant variables and macros (which you will never use) should be
>     capitalized, LIKE_THIS.  This includes enum values. Eg:
>       static const int FOO_BAR = 1;

I'm not sure we should mandate uppercase constants. Is there such a
(quasi) standard in the std C++ lib or CORBA IDL ? I think CORBA IDL
may follow such a rule, std C++ does not (iirc). But then, std C++ lib
uses all lowercase class names, too, so we can't justify it that way
easily :-)


> Commenting
> ----------
> This is not a comprehensive list; comment your code whenever you think
> it needs it, or whenever you think your reader needs it.  But there are
> a few things worth special note.
>  - Put Synopsis comments on everything!  [[FIXME: are there any
>     docs anywhere on how to format Synopsis comments?  Does
>     Synopsis support @return and the like?  This section should be
>     fleshed in with a description of how to actually write these
>     comments... or a link to such documentation, if it exists.]]

yeah, let's work on this later...
First and most useful rule: put '//.' prefixed comments in front of all
declarations if you want them to show up in a ref manual. (you want.)

>  - Put a comment starting with "FIXME:" if you are using a weak way to
>     do something, like not checking for the existance of files, code
>     that breaks in cornercases, etc.

FIXME: let's define a set of tags (tokens to be understood by synopsis)
to annotate code such as '@fixme' or '@obsolete'. Work out a list of
such tokens so they can be used consistency and help with code refactoring
later on.

> Using our Versioning System
> ---------------------------
> 
>  - Make sure your changes compile with gcc 2.95 at least, and
>     preferably also 3.1, before committing it or sending a patch to
>     the list. Make sure all demos that get build as part of the
>     Clients-C++ work and do the right thing.

TODO: let's define some rules on a specific page, so that we can update
them (for example once we decide to break gcc 2.9x compatibility, we
can just change that policy).


nice work, Nathaniel ! The document is remarkably small and clear.
Now let's put it into a prominent place for everybody to read.

There are other things to talk about, less concerned about the coding
itself, but more about team work and the developmental process. That
should go into a separate document I guess.

Nevertheless, I'll take the occasion to mention it here:

If you think something needs to be changed, please get in touch with
the author of the code and make sure you understand the intention of it,
and help the author to understand the problem you'd like to get fixed.

Fix it yourself only if the author has reviewed your patch, or has entitled
you to modify the code, or if the author can't be traced any more.
Emphasis is on concept/design/code review, to ensure consistency, and
good team spirit.

Regards,
		Stefan