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 ​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