[haiku-development] Re: Haiku Coding Guidelines Issues

On 2007-09-04 at 20:35:19 [+0200], Ryan Leavengood <leavengood@xxxxxxxxx> 
wrote:
> Here are quite a few things I am wondering about in regards to the
> coding guidelines:
> 
> In constructors does the colon always come before the parent class
> constructor call, or can a member initializer be there too if there is
> no parent class?
> 
> For example, assume Foo has no parent class, which is correct?
> 
> Foo::Foo(int32 param)
>     :
>     fMember1(param),
>     fMember2(param - 1),
>     fMember3(NULL)
> {
>     ...
> }
> 
> OR
> 
> Foo::Foo(int32 param)
>     : fMember1(param),
>     fMember2(param - 1),
>     fMember3(NULL)
> {
>     ...
> }

No real agreement here. I use the following:

Foo::Foo(int32 param)
    : fMember1(param),
      fMember2(param - 1),
      fMember3(NULL)
{
    ...
}

> The * for pointers is always located by the variable or method name,
> right? There are examples of this, but it isn't spelled out
> explicitly. For example:
> 
> class Example {
>     public:
>         Example();
>         ~Example();
> 
>         const char *Name();
> 
>     private:
>         BString *fName;
> }

Actually as OpenBeOS started that was more or less the convention, but 
since the '*' or '&' belong to the type some people (at least Axel and me) 
consequently sticking it to the type nowadays. According to his sample file 
Michael feels the same, but still has a space between type and '*'.

> Simple getters and setters can just be coded in the class declaration
> right? Using the above example class declaration, Name() could be:
> 
>         const char *Name() { return fName->String(); }
> 
> Right?

In private API's that's OK. In public ones you'd have to consider whether 
you really want it inline.

> Getters should not use the word "Get", but setters do use Set, right?
> For example:
> 
>     const char *Name();
>     void SetName(const char *name);

Yep.

> Is it preferred to "line up" the members of class declarations with
> tabs or not? It would probably be better to be explicit about this.
> Lining up looks better but could require more maintenance. StyledEdit
> has examples of what I mean by lining up.

I'm with Michael and Stippi on this one, but Axel doesn't like that much 
spacing. So no real agreement...

> The preferred order of things in headers and cpp files should probably
> be explicit. For example the declaration of constants or static
> methods should be where in header files? Before or after the class
> declaration?

I believe constants are pretty much always on top.

> What about in cpp files? Should the constants be first,
> then static methods, then the constructor, etc.?

I would mirror the method/constructor order of the header. And constants 
should probably go on top here, too, as do static variables and usually 
also globals.

> In headers is it preferable to include the headers for classes
> referenced in the header, or should simple declarations be used for
> classes which are only referred to? For example if a class subclasses
> BView and has a BString and BButton member, the header should include
> <View.h> but what about the string and button? We seem to be
> inconsistent about this.

In case of BStrings you usually don't have a choice, since classes mostly 
have a BString member, not a pointer to a BString. Otherwise the general 
rule is to keep header dependencies to a minimum, i.e. use "class Foo;" 
instead of "#include <Foo.h>" whenever possible.

> If the header for a file already includes a system header, should that
> file include it too? My gut says no, but I've seen this in the code,
> especially in cases where the header includes all the referenced files
> instead of just declaring the needed classes.

If something is included in the header I would remove it in the source file.

> Are there rules for when more than one class can be defined in the
> same file? Is it only acceptable when the second class is only used by
> the first?

I don't think there's anything wrong with putting related classes into the 
same header file. E.g. I would usually put a Listener/Visitor class into 
the same header as the class to be listened/visited, or in certain cases 
also an interface class and all its implementing classes. If the header 
gets too big (subjectively) it should be split.

> Do we want to establish a certain "style" for how the BApplication
> subclass is handled? I like Axel's style (at least what I have seen in
> PowerStatus and Sudoku), which is to have an [AppName].cpp which
> contains the application class declaration, implementation and the
> main method. The associated [AppName].h just has constant declarations
> (like for the app signature.) I suppose we don't have to have a
> standard for this, but it wouldn't hurt. Right now there are probably
> 4 or 5 slightly different styles of this in use.

I believe I usually do it the same way, but I don't think this deserves to 
be made a fixed rule.

> What are the rules for wrapping long lines? The same as long if
> conditions, where the line should be broken on an operator with the
> operator on the next line? Example:
> 
>     fSomeMember->someReallyLongMethodName(aVariableWithALongName.Height()
>         + SOME_CONSTANT_VALUE);

Yep.

> Opening brackets ({) should always be on the end of the first line,
> except for case statements, right?

The "case" block has nothing to do with the "switch/case" statement itself. 
It is merely used for variable scoping. All not otherwise motivated blocks 
shall have their opening brace on a new line.

CU, Ingo

Other related posts: