Naming Conventions

Use the following naming conventions for class, method, and variable names:

ClassNamesLikeThis
CONSTANTS_LIKE_THIS
instance_variables_like_this
method_variables_like_this
_semi_private_method_variables_like_this
__private_method_variables_like_this
public_method_names_like_this
_semi_private_method_names_like_this
__private_method_names_like_this

Exceptions are the class names for Opus variable classes (e.g. total_land_value), for model component classes (e.g. linear_utilities) and for pluggable model building blocks (e.g. mnl_probabilities). These all are lower case with underscores, since users specify these classes by strings and our experience is that it is much less confusing if strings are case-insensitive.

If a variable name won't be used but is needed, such as when a method returns a pair of values of which only one is used, start the variable name with dummy, as in:

coef, dummy = cm.estimate(specification, ...

It is important for a class to clearly communicate it's intended usage patterns. Part of having a well defined interface is being clear about which methods and which instance variables may be used from where. This helps others understand how to use the class, which helps prevent usage errors. Some methods, for instance, should only be called from within that class; perhaps they can only safely be called with data that is private to that object.

Python provides three types of method names that help span the public to private spectrum. Opus' convention is to use these three types of method names, as follows:

def foo(self):

This is a public method callable by anyone. Others objects can always call this and expect it to do the right thing. This corresponds to Java's public methods.

def _foo(self):

This is a semi-private method. It has a single leading underscore. It should only be called by another object that is closely related to this class, either by inheritance or by being in the same Python package. This corresponds to Java's protected and package methods, respectively.

def __foo(self):

This is a private method. It has two leading underscores. It should only be called from within this class. This corresponds to Java's private methods.

Always use setters and getters to access another object's instance variables. Accessing instance variables directly ties the outside object to the particular implementation of the instance variable. For instance, the object can no longer decide to compute the variable on each access. This leads to code that is harder to extend and maintain.

Class names should not start with an underscore.

Python has no special syntax or semantics for abstract classes, but good practice is to explicitly name a class as abstract, e.g. AbstractModel, if it is abstract.

Use lower case names with underscores for file names, e.g. my_stuff.py, for improved readability, and because some file systems are case sensitive while others are case insensitive. Beware that some file systems have limits on the length of file names, so don't make them too long.

Variable names should be at most 64 characters long, since MySQL does not allow column names with more than 64 characters.

Historical naming issues:

• Method names thatStartWithALowerCaseLetter are deprecated, although it is not urgent to change them.
• Method names ThatStartWithACapitalLetter should be renamed, since this style is used for class names instead.