Warning Code comments ;)

[Cyberman]

Ok I'm going to be going through some code and adding a bit of  commenting for doxygen.
Also converting prodigious use of constants into named explicite constants.

One simple question though, do we use a macro constant or an actual const.
IE
Code: [Select]

#define HOLY_MACRO_BATMAN 42f

versus
Code: [Select]

const float holy_macro_batman = 42f;

Also if a constant is only used in one area of the source code, say for example battle models. I suppose a globalized style declaration is a waste of time (or typing).
local
Ex:
Code: [Select]

const u32 l_number_of_bones = 0;

versus
globalized
Code: [Select]

const u32 ps1_ff7_number_of_bones = 0;

I prefer Macro's for MOST constants, save 1 type.  Anything that's used in a numerical expression in particular calculations, I prefer typed constants, to get explicite exceptions with any weird coding bugs that may crop up.

Cyb

 

[gigaherz]

I don't really like macros at all. In C/C++ they are still better than constants, but I agree with what someone told me, that macros is are an old feature for when compilers weren't complex enough, and that they should be mostly gone already (you should be able to use consts isntead of numeric defines and inline functions instead of macros in most cases).
Anyway there is something else I don't like in those examples: using _ in the constant/variable/function names, it looks just bad (IMO). I would do thing like someName or SomeName instead.

 

[mirex]

Hi, I'm not in the team, but I can give you some suggestions:

#defines are not nice for constants. they can be used, but its not nice. const's are better. #defines are for macros
I also suggest defining the constants inside classes (or namespaces?) to avoid conficts. To avoid defining constant for each instance of class making it static is a good way to go.

If you are defining 'int' constants which you want to use in the definition of code (for example as size of the array) then const would not work, in that case I suggest to define it as in enumerate.

Example:

Code: [Select]

header:  class GearsFileDefinition {    static const int number_of_bones;    static const std::string init_file_name;    enum { filename_length = 34 } ;    static const char filename[ filename_length ]; } ;cpp:// initialization of static variablesconst int GearsFileDefinition::number_of_bones = 4;const std::string GearsFileDefinition::init_file_name = "gears.ini";const char GearsFileDefinition::filename[ GearsFileDefinition::filename_length ] = { "Hello" } ;usage inside the class:  for( i=0; i<number_of_bones; i++ ) {     ...  }usage outside of class:   for( i=0; i<GearsFileDefinition::number_of_bones; i++ ) {     ...  }  Log( GearsFileDefinition::filename );

Hope that you understand the code, if you don't please ask.


gigaherz: naming convention depends on users. I saw few of conventions and each was hated by someone else

 

[gigaherz]

gigaherz: naming convention depends on users. I saw few of conventions and each was hated by someone else

I know, but I still think using _ in identifiers seems like wasting chars...

If you are defining 'int' constants which you want to use in the definition of code (for example as size of the array) then const would not work, in that case I suggest to define it as in enumerate.

If you can't use a const var in an array declaration, then it's an horrible flaw in the language. A const should be handled internally, replacing it in constant expressions or reading it from memory where it's better, but I suppose the definition for a "const" in C/C++ is just a variable that can't be written (so it's no longer variable)...

 

[mirex]

I think that its still a variable, as you can create a pointer to it. Imagine situation:

const char noname[] = "null";

const char* GetName( int number )
{
   if ( something )
     return somearray[ number ];
  else
     return noname;
}

IMO waste of chars is okay if there is better readability of code. But its all about one's style.

 

[Cyberman]

There are some things you can do with macros you can't in C++ however I digress.

The important thing is to have some consistancy.  Camel versus _ spaced etc is a style issue I am more concerned with a consistant naming convention for all variables and constants.  Camel or Cow code I couldn't care less, as long as we all use the same thing.
As far as I can tell Akari is using .. I'm not sure what it's called but anyhow She is using
Code: [Select]

int this_variable_is_nothing;

instead of
Code: [Select]

int ThisVariableIsNothing;

Camel Code.
So being unbiased I would use whatever has been most commonly used.

As for consts, I suppose local and global consts should be distinguished no? IE If a constant is local to a module then it would be
Code: [Select]

const float l_this_variable_is_nothing = 3.14159265f;

l_ indicating it's local to the module.

This works fine when using name spaces even. (Name spaces have bit me recently dang it)

Well I'll twiddle later I've got more looking for stuff to do.

Cyb

 

[Akari]

For the names I use:

Code: [Select]

ThisIsClassNameThisIsClassMethod()this_is_function()thisIsMethodOrFunctionArgumentthis_is_local_variable

This way you always know what you see from the very first glance to name.
Some where here was topic that have link to this notation.

 

[halkun]

The Dude abides...

Even though I don't like camelHump notation, but can deal with it, Hungarian notation is lothesome and doen't really add anything to readability that can't be understood from context.

Going by my C background, macros shoudn't be typed. Let the preprosser do it's job and the compiler do it's job. The preprosser should help set the environment and work with autotools.

My input anyway.