I'd like to get a consensus on naming for IMP modules and classes (well, OK, I'm going to say what I think it should be, and people can agree or disagree).
Currently, on the C++ side, all classes use a Capitalized_Words_With_Underscores naming scheme (e.g. Restraint_Set) and live in the 'imp' namespace. This is translated to the 'imp2' module on the Python side, with the same class names. This has a few problems:
1. The Python 'imp2' name is ugly - Bret presumably had to call it that because Python has a built-in module called 'imp' already. The Python guys (http://www.python.org/dev/peps/pep-0008/) prefer "short, lower-case" names for modules, but I don't think this really makes sense for initialisms anyway - for example, there are already EMAN and CORBA Python libraries out there (the BALL guys also use "BALL"). So I propose "IMP".
2. Python pretty much mandates CamelCase for class names (e.g. RestraintSet). Since the Python class names match the C++ names, we either have to do lots of ugly renaming in the Python interface, or just rename the C++ classes to match. Lots of C++ people use CamelCase anyway (e.g. BALL at http://www.bioinf.uni-sb.de/OK/BALL/Documentation/1.1.1/V1.1.1/hierarchy_htm...). So I propose CamelCase names for IMP C++ classes.
3. There are a bunch of utility Python modules in tests/python_libs: IMP_Modeller_Intf.py IMP_Test.py IMP_Utils.py load_imp_xml_model.py I propose renaming these to IMP.modeller, IMP.test, IMP.utils, IMP.xml.
4. I propose renaming derived classes such as imp::RSR_Exclusion_Volume (exclusion volume restraint, although what the second R in RSR stands for, I don't know ;) as either imp::ExclusionVolumeRestraint or imp::restraint::ExclusionVolume. I prefer the latter because it would more easily translate into the Python IMP.restraint.ExclusionVolume class, and by changing from a class name prefix (RSR) to a namespace we both allow for more readable Python scripts (e.g. "import IMP.restraint as r; r.ExclusionVolume()" or even "from IMP.restraint import *"), and finally because this would greatly simplify moving restraints to their own C++ module.
What do others think?
Ben
The python module name and the C++ namespace should probably match since they play the same role (so "namespace IMP"). Otherwise what you say sounds reasonable.
On Oct 11, 2007, at 2:03 PM, Ben Webb wrote:
> I'd like to get a consensus on naming for IMP modules and classes > (well, OK, I'm going to say what I think it should be, and people > can agree or disagree). > > Currently, on the C++ side, all classes use a > Capitalized_Words_With_Underscores naming scheme (e.g. > Restraint_Set) and live in the 'imp' namespace. This is translated > to the 'imp2' module on the Python side, with the same class names. > This has a few problems: > > 1. The Python 'imp2' name is ugly - Bret presumably had to call it > that because Python has a built-in module called 'imp' already. The > Python guys (http://www.python.org/dev/peps/pep-0008/) prefer > "short, lower-case" names for modules, but I don't think this > really makes sense for initialisms anyway - for example, there are > already EMAN and CORBA Python libraries out there (the BALL guys > also use "BALL"). So I propose "IMP". > > 2. Python pretty much mandates CamelCase for class names (e.g. > RestraintSet). Since the Python class names match the C++ names, we > either have to do lots of ugly renaming in the Python interface, or > just rename the C++ classes to match. Lots of C++ people use > CamelCase anyway (e.g. BALL at http://www.bioinf.uni-sb.de/OK/BALL/ > Documentation/1.1.1/V1.1.1/hierarchy_html). So I propose CamelCase > names for IMP C++ classes. > > 3. There are a bunch of utility Python modules in tests/ > python_libs: IMP_Modeller_Intf.py IMP_Test.py IMP_Utils.py > load_imp_xml_model.py > I propose renaming these to IMP.modeller, IMP.test, IMP.utils, > IMP.xml. > > 4. I propose renaming derived classes such as > imp::RSR_Exclusion_Volume (exclusion volume restraint, although > what the second R in RSR stands for, I don't know ;) as either > imp::ExclusionVolumeRestraint or imp::restraint::ExclusionVolume. I > prefer the latter because it would more easily translate into the > Python IMP.restraint.ExclusionVolume class, and by changing from a > class name prefix (RSR) to a namespace we both allow for more > readable Python scripts (e.g. "import IMP.restraint as r; > r.ExclusionVolume()" or even "from IMP.restraint import *"), and > finally because this would greatly simplify moving restraints to > their own C++ module. > > What do others think? > > Ben > -- > ben@salilab.org http://salilab.org/~ben/ > "It is a capital mistake to theorize before one has data." > - Sir Arthur Conan Doyle
On Oct 11, 2007, at 2:03 PM, Ben Webb wrote:
> I'd like to get a consensus on naming for IMP modules and classes > (well, OK, I'm going to say what I think it should be, and people > can agree or disagree). > > Currently, on the C++ side, all classes use a > Capitalized_Words_With_Underscores naming scheme (e.g. > Restraint_Set) and live in the 'imp' namespace. This is translated > to the 'imp2' module on the Python side, with the same class names. > This has a few problems: > > 1. The Python 'imp2' name is ugly - Bret presumably had to call it > that because Python has a built-in module called 'imp' already. The > Python guys (http://www.python.org/dev/peps/pep-0008/) prefer > "short, lower-case" names for modules, but I don't think this > really makes sense for initialisms anyway - for example, there are > already EMAN and CORBA Python libraries out there (the BALL guys > also use "BALL"). So I propose "IMP". > yes
> 2. Python pretty much mandates CamelCase for class names (e.g. > RestraintSet). Since the Python class names match the C++ names, we > either have to do lots of ugly renaming in the Python interface, or > just rename the C++ classes to match. Lots of C++ people use > CamelCase anyway (e.g. BALL at http://www.bioinf.uni-sb.de/OK/BALL/ > Documentation/1.1.1/V1.1.1/hierarchy_html). So I propose CamelCase > names for IMP C++ classes. > I use CamelCase We should probably have some consensus on function names and attribute names I would go with:
get/set ( Daniel's convention): protected: int x_; public: int x() const {return x;} void set_x(int x) { x_=x;}
and thus all class attributes should be name_ as well ( just to stay consistent)
and for other functions I would use CamelCase as well
> 3. There are a bunch of utility Python modules in tests/ > python_libs: IMP_Modeller_Intf.py IMP_Test.py IMP_Utils.py > load_imp_xml_model.py > I propose renaming these to IMP.modeller, IMP.test, IMP.utils, > IMP.xml.
yes > > 4. I propose renaming derived classes such as > imp::RSR_Exclusion_Volume (exclusion volume restraint, although > what the second R in RSR stands for, I don't know ;) as either > imp::ExclusionVolumeRestraint or imp::restraint::ExclusionVolume. I > prefer the latter because it would more easily translate into the > Python IMP.restraint.ExclusionVolume class, and by changing from a > class name prefix (RSR) to a namespace we both allow for more > readable Python scripts (e.g. "import IMP.restraint as r; > r.ExclusionVolume()" or even "from IMP.restraint import *"), and > finally because this would greatly simplify moving restraints to > their own C++ module. > >
I would go with imp::ExclusionVolumeRestraint and imp::CGOptimizer - to make it more self explanatory
5. using namespace
are we ok with using namespace std for the IMP classes ??
6. public/protected/private
I think that all attributes that can be derived should be protected and other internal attributes ( like for example was_calculated )
> What do others think? > > Ben > -- > ben@salilab.org http://salilab.org/~ben/ > "It is a capital mistake to theorize before one has data." > - Sir Arthur Conan Doyle
>> > I use CamelCase > We should probably have some consensus on function names and > attribute names I would go with: > > get/set ( Daniel's convention): > protected: > int x_; > public: > int x() const {return x;} imp mostly uses get_x() sort of names so far (there are a couple of exceptions).
> void set_x(int x) { x_=x;} > > and thus all class attributes should be name_ as well ( just to > stay consistent) > > and for other functions I would use CamelCase as well Currently all classes are CamelCase and all functions_use_underscores. I like having the distinction as C++ can be ambiguous about what is a function and what is an object (in fact, for certain syntax it is undefined whether you are talking about a class or a function).
> > 5. using namespace > > are we ok with using namespace std for the IMP classes ?? Within a method is fine. Polluting someone else's code or the imp namespace, not so much :-)
Daniel Russel wrote: > imp mostly uses get_x() sort of names so far (there are a couple of > exceptions).
True, and I think we should stay with that - makes it more obvious that you're calling a (generally const, returning a value) method.
>> and for other functions I would use CamelCase as well > Currently all classes are CamelCase and all functions_use_underscores. I > like having the distinction as C++ can be ambiguous about what is a > function and what is an object (in fact, for certain syntax it is > undefined whether you are talking about a class or a function).
I agree with Daniel here. Our existing code is lowercase separated by underscores, so we may as well stick with it. Plus, it does remove ambiguity. Plus, the Python folks mandate it for Python methods anyway, so we don't have to rename anything to keep the Python interface clean.
>> 5. using namespace >> are we ok with using namespace std for the IMP classes ?? > Within a method is fine. Polluting someone else's code or the imp > namespace, not so much :-)
Agreed. I'd recommend against "using namespace" if possible.
Ben
participants (3)
-
Ben Webb -
Daniel Russel -
Keren Lasker