[gmx-developers] abstract type convention?

[Erik Lindahl]

Hi,

On Jun 10, 2013, at 9:02 AM, Berk Hess <hess at kth.se> wrote:
> 
> I have (finally) started working on disentangling the data structures in preparation for the modularization.
> I want to start with t_forcerec and t_commrec.
> But before starting the actual rewrite, I want to ask what convention we should use for abstract data types.

Great initiative, although remember that we should do this work as C++-ification in the head branch, not continue development in the 4.6 tree :-)

> For now I want to keep most of the contents of these structs the same, but separate and hide it inside in several abstract data types. We have different naming scheme for this in the current code, but it seems that the one below is most used (at least I seem to have switched to that lately). Can we agree on this, or are there better suggestions?

I think we decided to move towards camelCase when we transfer to C++, partly to see what code has been converted, but also because it's slightly more compact.
> 
> Slightly unrelated, I don't want to use the gmx_ prefix for everything (like Erik has been doing lately), only for data structures which would be accessible in the user API. The API has not been defined yet, so this might change over time.

Things are slightly different in C++ I would imagine - we should probably use a "gmx" namespace, and possibly sub-namespaces if people don't like to include module names in the function names.

However, when it comes to routine naming (or sub-namespaces), I would prefer that we try hard to err on the side of too explicit names rather than our current abbreviations that are very hard to understand for somebody who did not write a particular piece of code.


My suggestion would be that we only use short names for static functions present in the same file unit - in particular this means they are easy to find with an instant "search". Even for these functions and datatypes the names should be expanded far enough that anybody can understand what they do or contain based only on the name. For everything else, the name should also explain in what module the structure or function is defined. This way it helps *us* too, not only a third-party user calling our library.


I think the added value in self-documentation is an order of magnitude more useful for the project compared to saving a few keystrokes, in particular when most editors have great auto-completion functionality today!

I promise to repent the day people complain we have too much documentation :-)

Cheers,

Erik

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://maillist.sys.kth.se/pipermail/gromacs.org_gmx-developers/attachments/20130610/bb49c498/attachment.html>