Changes between Initial Version and Version 1 of PyBindings_Coding_Standards

Timestamp:

Apr 28, 2014 2:55:41 PM (10 years ago)

Author:

trac

Comment:

--

PyBindings_Coding_Standards

@@ +1 @@
+Coding standards for pybindings are a work in progress. Feel free to add your $0.02 here.
+
+== Rationale ==
+
+It is useful for each IceTray class exposed via pybindings to have a consistent interface. If we can settle on a reasonable set of standards, then an average coder should be able to guess the method names of a class with reasonable accuracy without slogging through the documentation.
+
+== Naming schemes ==
+
+The interface exposed through pybindings should conform to the [http://www.python.org/dev/peps/pep-0008/ Style Guide for Python Code] as closely as possible. The relevant points of this recommendation are:
+
+- Classes should be named in UpperCamelCase
+- Property names should be snake_case, or lower case with words separated by underscores
+
+TBD: what do do about existing UpperCamelCase method names?
+
+== Enumerated types ==
+
+Enumerated types should be named in UpperCamelCase and their elements in UPPER_CASE.
+
+== Superfluous Get/Set methods ==
+
+In C++, data members are often made private and only exposed through Get/Set methods. The Python language includes object properties, a language-level abstraction for this kind of encapsulation. Instead of exposing the methods GetX() and SetX(float x), wrap them in the property x. The user will then be able to call foo.x or foo.x = 3.2 without having to care whether x is a public data member or a private data member wrapped in Get/Set methods.
+
+== Container types ==
+
+The C++ coding standards require that a vector of SomeType be named SomeTypeVect and a map be named SomeTypeMap. On the python side, there is a veritable zoo of naming schemes. Spotted in the wild:
+
+- vector_SomeType
+- SomeTypeVect
+- SomeTimeSeries
+- Map_OMKey_SomeType
+- map_SomeType
+- SomeTypeSeriesMap (for a map of vectors of SomeType)
+
+This isn't really a problem, since one usually doesn't need the name of the container class explicitly (instantiate a new container with some_frame_object.__class__(), for example). Still, it might be nice to clean these up.
+
+== Docstrings ==
+
+Whenever possible, include docstrings in RST format for non-obvious methods and properties. 
+
+== Private container members ==
+
+Some classes keep a private vector of information exposed via 1-argument Get and 2-argument Set methods (e.g. I3DOMCalibration.GetATWDGain(int channel), I3DOMCalibration.SetATWDGain(int channel, double gain)). There's no readily apparent way to expose such members is a natural way. Ideas? 
+
+== Other ideas ==
+