An open source framework for modeling [electric] machinery.
All contributors to eMach are asked to use specific MATLAB code style, use MATLAB's object oriented programming (OOP) capabilities, and follow the SOLIDD design principles—all of which are now outlined.
Using a consist writing style makes shared code more maintainable, useful, and understandable. Contributors to eMach should follow the guidelines provided here.
A brief summary of guidelines for names includes:
- Avoid using excessively short names: instead, favor full words to convey meaning
- Function and variable names: start lower case and then move to camel case, i.e.
toInch() - Class names: start upper case and then move to camel case, i.e.
MaterialGeneric
Follow the MATLAB editor's guidelines on maximum line length. Wrapping to multiple lines is preferred over code that has excessively wide lines. This is for readibility and printability reasons.
The reference manual for MATLAB OOP can be found here.
Those looking to quickly grasp the key concepts of Matlab's implementation of OOP are referred to Kevin Murphy's Object Oriented Programming in Matlab: basics guide and the official MATLAB class syntax guide. MATLAB's instructions for creating help documentation of classes can be found here.
SOLIDD is an acronymn for the following code design guidelines:
- Single responsibility principle “a class should have only a single responsibility” or “a class should have only one reason to change”
- Open/closed principle "software entities … should be open for extension, but closed for modification."
- Liskov substitution principle "objects in a program should be replaceable with instances of their subtypes without altering the correctness of that program."
- Interface segregation principle "Many client-specific interfaces are better than one general-purpose interface."
- Dependency inversion principle One should "depend upon abstractions, [not] concretions."
- Don't repeat yourself
These guidelines come out of the Agile community (specifically, Robert C. Martin) and are intended to make code flexible and maintainable. They are subtle and require close study to grasp their full implications.
Note that MATLAB is a dynamically typed language and therefore does not impose type restrictions on variables. This can make adherence to the SOLIDD princples challenging. eMach enforces typing manually enforced by calling validateattributes like this:
validateattributes(obj.dim_depth,{'dimLinear'},{'nonnegative', 'nonempty'})validateattributes(compArcObj,{'compArc'},{'nonempty'})
For example, see the MATLAB DimLinear class.
Several useful resources on the SOLIDD guidelines are assembled here: