Menu
▾
▴
Re: [Ne-odc-devel] Coding Convention Proposal
|
From: Bertolt S. <ber...@in...> - 2002-09-09 11:55:17
|
Am Samstag, 31. August 2002 19:35 schrieb Thomas Huth:
> On Thu, 29 Aug 2002 08:28:46 +0200, Holger Dammertz wrote:
> > General/Unsorted:
> > ------------------
> > - Always put the constant on the left hand side of an equality/inequa=
lity
> > comparison (I think the reason should be clear). For example:
> > if (6 =3D=3D iErrorNum)
>
> Ok, this might be usefull for avoiding the "=3D" vs. "=3D=3D" typo... b=
ut it is
> IMHO quite unusual to always write comparisons this way (and looks quit=
e
> ugly in my eyes, too). Experienced C/C++/Java coders also shouldn't hav=
e
> problems with this typing error, so I would prefer to drop this rule.
I agree, we can drop this rule.
> > - Methods should limit themselves to a single page of code.
what to do if not?
>
> > - each class should have it's own .h and .cpp file (and this are the =
only
> > allowed extensions)
>
> What about totally virtual classes? Their .cpp would be empty. Can it b=
e
> omitted then?
Generally yes.
But in a Java GUI i.e. you will have lots of ActionListener-classes for o=
nly=20
one Button. We should declare exceptions from this rule.
>
> > Formatting Conventions:
> > ------------------------
> > - one space after a comma, an "if" or an "switch":
> > if ((1 =3D=3D iCount) || (5 =3D=3D CalcMax(7, 19)))
> > {
> > ...
> > }
>
> Why spaces after an "if" or "switch"? I always saw "if" and "switch" li=
ke
> normal function calls, and you normally don't add a space there, too!
> And what about "for" and "while" expressions?
one space after a comma is usual
I think it don't care if there is a space after an "if", "switch", ... or=
not
>
> > - Declaration blocks should be aligned in the following way:
> > /** comment */
> > GMesh3D* m_pMesh;
> > GSubMesh3D* m_pSubMesh;
> > /** comment */
> > float* m_pRotMatrix;
>
> First this seems to be a good idea... but then: What if you have to add=
a
> new variable with a very long type name later? E.g.:
>
> GVeryVeryLongTypeName3D* m_dontKnowWhat;
>
> =3D> Then you have to re-align all other variables in that declaration =
block,
> this is a lot of anoying extra-work and makes CVS-diffs less readable.
> Since there is already another rule for better readability ("only decla=
re
> one variable per line"), I would like to see this rule to be dropped, t=
oo.
I don't see an advantage in this rule...
But Thomas mentioned many disadvantages.
> > - Similarly blocks of initialization of variables should be tabulated=
:
> > clpInstance =3D this;
> > iActiveElements =3D 0;
>
> Same as above. I don't think it's a good idea.
> > - if (condition) // Comment
> > {
> > }
> > else if (condition) // Comment
> > {
> > }
> > else // Comment
> > {
> > }
>
> The way that you placed the comments, you will often run in trouble
> regarding the 78-colums rule...
First: -open bracket in a new line
Second: possibilities where to place the comment:
1.=20
if (condition)
{ // comment
...
} // end comment
2.
if (condition)
{
// comment
...
} // end comment
the "end comment" is optional. I think its useful if there is a high=20
identation level. So you can easier see what block this }-bracket closes.
>
> > - switch (...)
> > {
> > case 1:
> > ...
> > // FALL THROUGH
> > case 2:
> > {
> > int v;
> > ...
> > }
> > break;
> >
> > default:
> > }
>
> This example seems to be very confusing: What do you want to say exactl=
y
> with it? And how to exactly indent the instructions between two case
> clauses? You should write such examples without an describing text abov=
e
> it.
> BTW: Most of those "Formatting conventions" can simply be covered by
> declaring a certain "indent" or "astyle" format. So every coder could u=
se
> indent or astyle to format his source code in the right way before
> committing it to the CVS repository. (BTW: I'm not sure if indent also
> supports C++, and since astyle also supports Java, this or something
> equivalent might be the better choice).
I think thats a good idea.
>
> > Naming Conventions:
> > --------------------
> >
> > Method Naming:
> > - The first character in the name is upper case (this could
> > be discussed, but see my reason below)
> >
> > Member Variable Naming:
> > I have two possible conventions in mind:
> > 1; (similar to what we are using already)
> > - all member variables start with a lower case letter
> > - private member variables start with an underbar
> > When methods start with a upper case letter and variables with
> > a lower case letter, they are easyly distinguishable.
>
> Methods and variables are _already easyly distinguishable, since method=
s
> have a bracket afterwards! So I really like to keep it like the old way
> was, variables and methods both starting with a lowercase letter. Also =
note
> that you won't be able to distinguish methods and classes when both sta=
rt
> with a capital letter!
I think this is our habit.
>
> > 2; (I would prefer this)
> > - each variable starts with a prefix (describing access type and
> > data type) and then apply the same rules as for method naming:
> > Access Prefix:
> > m before the name of a member variable
> > ms before the name of a static variable
> > (Perhaps we could add here some more to distinguish between
> > public, protected and private variables;
> > The hungarian notation uses also g and gs for global (static)
> > variables.)
>
> This prefix method also sounds quite usable, but I wouldn't add a lette=
r
> for that public/protected/private stuff, since this might change someti=
mes
> and then you have to rename all places where the variable occurs in the
> source code.
>
> > Data Types:
> > p for a pointer
> > s for int16/short
> > us for uint16
> > i for int32
> > ui for uint32
> > q for int64
> > uq for uint64
> > f for real32/float
> > d for real64/double
> > b for bool
> > uc for uint8 or byte
> > sz for a C string
> > str for a STL string
> > tag for any struct
> > cl for any class
> > ct for any enum
>
> Well, I really don't like that Hungarian notation method - for example =
what
> if you change the type of a variable (e.g. from float to double)? Yes, =
you
> have to rename it everywhere in the source code. If you want to know ab=
out
> the type of a variable, simply have a look in the tiny .h file or the
> documentation generated by Doxygen.
>
> > Perhaps it might be more readable to write an underbar after the
> > access prefix (for example: Mesh3D* m_clpGraphicMesh)
>
> Oh no, yet another key more to type ;-) But it really looks better, I
> think.
I don't mind.
>
> > What also needs to be defined (but I wait for your suggestions):
> > - the get and set methods
>
> Why needs this extra definitions? Simply write a getVariable() and a
> setVariable() method!?
thats right
>
> > - single line comments (in the code) should be written in this form:
> > /* comment */
> > some code...
>
> What about:
> // comment
> some code...
> ???
Why not "// comment" ?
>
>
> BTW: What about comments in the .cpp fiels to separate methods? Or what
> about separation lines like this:
> //*******************************************************
> Should/Must they be used in the code?
>
what about this? (or something similar)
// *************** method name above ********************
//
// ------------------ method name below --------------------------
> > Open points:
> > - How strict should we force the use of a centralized logger=20
> > (->error-handling)?
we can say, if s.o. commit code into CVS there isn't any system.out.print=
ln()=20
in the code (or only in outcommented form for future testing)
> Thomas
|