Dear devs,
i have a question about the function naming guidline of GRASS.
I would like to add a guidline to the SUBMITTING file.
But the problem is that we have two naming conventions
for library functions in GRASS.
The common convention is: G_fatal_error(), to place a "_" between the function description strings,
but within the G3D library a different convention was used: G3d_fatalError().
Personally i like the function name convention of the G3D lib, because this
convention is used in other libraries i am programming with and i think its better readable.
So i named all the functions in my r3.* modules like the G3D lib standard.
But i would like to see a uniform programming standard/API within GRASS, so what to do?
Should the G3D library API be an exception and all the user defined function names should use
the common API (G_name_name), or should the module developer decide on his own what convention to use?
Or should we/i rename all G3D function names to meet the common convention?
Well thats not impossible, but a huge amount of work (the testing and the docs).
In my opinion a function naming guidline is important, like the coding standards of VTK:
http://www.vtk.org/Wiki/VTK_Coding_Standards
Also a clear guidline how to name a module (not more than 2 dots in name?) and how to name
the command line variables would be helpful.
What do you think?
Best regards
Soeren
Soeren Gebbert wrote:
i have a question about the function naming guidline of GRASS.
I would like to add a guidline to the SUBMITTING file.
But the problem is that we have two naming conventions
for library functions in GRASS.
The common convention is: G_fatal_error(), to place a "_" between the function description strings,
but within the G3D library a different convention was used: G3d_fatalError().
Personally i like the function name convention of the G3D lib, because this
convention is used in other libraries i am programming with and i think its better readable.
So i named all the functions in my r3.* modules like the G3D lib standard.
But i would like to see a uniform programming standard/API within GRASS, so what to do?
Should the G3D library API be an exception and all the user defined function names should use
the common API (G_name_name), or should the module developer decide on his own what convention to use?
All of the core libraries use underscores rather than mixed case. The
only libraries which use mixed case are third-party add-ons which were
developed separately then incorporated into GRASS later.
FWIW, I strongly prefer underscores; it's also the official GNU naming
convention.
Or should we/i rename all G3D function names to meet the common convention?
Well thats not impossible, but a huge amount of work (the testing and the docs).
I don't consider renaming to be a priority. It might be worth doing if
the library was undergoing a major overhaul, but otherwise there are
better uses of developer time.
--
Glynn Clements <glynn@gclements.plus.com>
Hello Glynn,
thank you for your suggestions.
On Monday 07 August 2006 21:45, Glynn Clements wrote:
Soeren Gebbert wrote:
> i have a question about the function naming guidline of GRASS.
> I would like to add a guidline to the SUBMITTING file.
>
> But the problem is that we have two naming conventions
> for library functions in GRASS.
> The common convention is: G_fatal_error(), to place a "_" between the function description strings,
> but within the G3D library a different convention was used: G3d_fatalError().
>
> Personally i like the function name convention of the G3D lib, because this
> convention is used in other libraries i am programming with and i think its better readable.
> So i named all the functions in my r3.* modules like the G3D lib standard.
>
> But i would like to see a uniform programming standard/API within GRASS, so what to do?
>
> Should the G3D library API be an exception and all the user defined function names should use
> the common API (G_name_name), or should the module developer decide on his own what convention to use?
All of the core libraries use underscores rather than mixed case. The
only libraries which use mixed case are third-party add-ons which were
developed separately then incorporated into GRASS later.
FWIW, I strongly prefer underscores; it's also the official GNU naming
convention.
Very good, a clear statement. 
I will rename all functions i have created in my modules.
I will also add this as coding standard to the submission guidline.
> Or should we/i rename all G3D function names to meet the common convention?
> Well thats not impossible, but a huge amount of work (the testing and the docs).
I don't consider renaming to be a priority. It might be worth doing if
the library was undergoing a major overhaul, but otherwise there are
better uses of developer time.
I will put the "renaming" to the todo list for grass7, because i plan
to extent/rewrite the documentation of this lib.
Best regards
Soeren