[openbeos] Re: Coding Style Guideline
- From: "Axel Dörfler" <axeld@xxxxxxxxxxxxxxxx>
- To: openbeos@xxxxxxxxxxxxx
- Date: Tue, 12 Jul 2005 14:57:50 +0200 CEST
Michael Lotz <mmlr@xxxxxxxx> wrote:
> But when trying to apply "the code guideline" I noticed that there is
> not really one complete guideline. As I understand it the official
> style
> guideline is the one from OpenTracker, which is also linked from
> Haiku-OS.org (Contribute -> Coding Guidelines). I read them some
> times
> in the past and just read them again.
> But I came to the conclusion that they are just not in line with the
> Be
> header style I adapted to and use since quite some time (which rather
> surprised me as the OpenTracker headers should be similar to the Be
> headers).
Right, the Be header style is not what we're doing. Also, there is,
AFAICT no single Be header style, either.
> Foo( int32 indented_to_align_args,
> int32 if_wrapped_over,
> int32 multiple_lines);
This I find particularly ugly :-)
The indenting is also something I don't completely agree with, though.
For the following case, though, I think the standard is definitely the
best and cleanest approach:
1)
some_func(and, some, long, arguments,
that, spread, over, the, next, line);
some_other_func(and, some, long, arguments,
that, spread, over, the, next, line);
Unlike:
2)
some_func(and, some, long, arguments,
that, spread, over, the, next, line);
some_other_func(and, some, long, arguments,
that, spread, over, the, next, line);
or even:
3)
some_func( and, some, long, arguments,
that, spread, over, the, next, line);
some_other_func( and, some, long, arguments,
that, spread, over, the, next, line);
I find both 2&3 very distracting to read.
However, it's only a small deviation from the style guidelines, so I
guess we can
live with them easily.
I also don't like:
a = 2;
b = "this";
c " 3;
If it's a longer list, or only a single line, you have to jump quite a
bit to see what variable gets which value assigned, you cannot easily
grasp it with a single look, and also might confuse the lines when
doing this.
In another case, though, I find our styleguide not so nice:
status_t status = some_func(and, some, long, arguments,
that, spread, over, the, next, line);
and:
virtual status_t some_func(and, some, long, arguments,
that, spread, over, the, next, line);
In these cases, the return type and the variable declaration get a
little bit lost in the flow.
> static BArchivable *Instantiate(BMessage *data);
> virtual status_t Archive(BMessage *data, bool deep)
> const;
>
> virtual void Pulse();
> virtual void FrameMoved(BPoint new_position);
>
> private:
> int32 fMember1;
> int32 fMember2;
> const char *fMember3;
> };
This style I often prefer as well.
> While the first one may be more "structured" I find the second one
> far
> more easy to read. The keywords like "virtual", "static", "typedef"
> or
> "friend" are on the left, then a tab, the type, then tabs to align
> with
> the rest, and then the function/variable. If there is no keyword,
> there
> are two tabs instead. The only keyword where this doesn't work out is
> "volatile" because it's too long. Also all the "*" or "&" stick to
> the
> variables/functions in the Be headers.
I actually recently adopted the
char* fName;
style, as it makes a lot more sense (especially when using "const").
But it's definitely not the style thought by the language, otherwise
comma separated variable definition would not be part of the grammar.
Logical but wrong:
char* fName, fTitle;
Our usual style and correct:
char *fName, *fTitle;
The general solution to the first one seems to be to avoid comma
separated definitions :-)
Anyway, I don't particularly care which style is used here, although I
think we should stay consistent at least in the public headers.
> This:
> <-- line starts here
> Vs. that:
> <-- line starts here
> I personally find the first one better, as you can just start typing
> and
> don't have to care about indenting at all, but this obviously depends
> on
> personal taste and your editor of choice. I think things like this
> should just be decided and written down.
Some editors actually remove the superfluous indenting. If this should
be part of the style guide, I would definitely prefer to get rid of all
these dispensable bytes as well.
I also wanted to add an option to Pe that does this by default, but
didn't find the time yet :)
> So my question is: Should I try to write a complete guideline as a
> mix
> between OpenTracker and Be headers, should I use both as I like,
> should
> I just stick with one, or should I just leave the whole topic and do
> something else.
The Be header style is not part of our style guide, nor should it be, I
think.
If I were to change the style guide, I'd do the following changes to
what I discussed above:
status_t status = some_func(and, some, long, arguments,
that, spread, over, the, next, line);
and:
virtual status_t some_func(and, some, long, arguments,
that, spread, over, the, next, line);
for the second case, I would also like to have all 2nd lines start at
the same position.
> Applying style guides is just a very easy task you can do without the
> need for a BeOS machine or other developing platform. And you can
> look
> over the code to eliminate old variables/forward declarations/
> includes
> that are not needed anymore in the same run. Perfect for the time
> between leaving home in the morning and getting back at evening, if
> you
> know what I mean.
>
> Thoughts?
I think we should just stay with what he have, and eventually making it
more complete, and maybe make some parts advisory only.
Bye,
Axel.
Other related posts:
