Clean code rules

Welcome to the clean code rules page of the Swan wiki! During the development of any code, the programmer not only wants to obtain the desired results once the project is finished but also a code which is readable and easily expandable. Therefore, in Swan we have defined a set of rules to create our own clean code in a fast and efficient way.

This page will expose you different rules that might be used as a checklist while working in your personal branch of the project. The clean practices will be divided mainly in two parts: morphology and relevance.

Morphology

The morphology deals with the appearance of the code from a superficial point of view - i.e how any word must be written -, regarding the construction of variables, functions or classes. The rules concerning morphology are depicted below:

• Every term in the code will not use an underscore symbol (_) to separate words. Instead, we will use capital letters. For instance, we write "HelloWorld", rather than "Hello_world"; or "stiffType", rather than "stiff_type".
• The name of a class must be a noun, starting with a capital letter. Example: "StressComputer".
• An instance of a class must be also a noun, but starting with a lower case letter. Example :"stressObject".
• The name of a property or variable must be a noun, starting with a lower case letter (here some exception can be found, for instance the use of a single letter "K" instead of "stiffnessMatrix").
• The name of a function must be a verb, starting with a lower case letter. An exception to this rule: the constructor function (see Relevance). Example: "computeVonMisesStress".

Relevance

The relevance deals with the internal significance of the code, how it is connected with its surrounding and the degree of simplicity. For instance, the cohesion between the functions and the class that they serve, the type of access used for every property and function or the need to avoid code repetition, between others. The rules concerning relevance are depicted below:

• When defining an independent class, the first public function must be the constructor. This takes the following form: "function obj = ClassName(cParams)". Inside the constructor, a private init function is usually instantiated to assign values to some properties by using the external cParams structure.
• Avoid the definition of static functions. It is better to define private functions where the object interacts with its own properties.
• Define simple atomic functions. It is preferable to use a lot of small functions (simple tasks) rather than a single huge function.
• Validate your tests before committing your new changes, always.
• Do not create classes with more than 100 lines.
• Make sure that functions have some cohesion with its class. You cannot create functions which computation is not inside the scope of your class (for instance, computing the stress inside a class called StiffnessMatrixComputer).
• Compose classes with other classes when optimizing your code.
• Do not repeat code. Instead, create new classes or functions that uses this part of the code and are later instantiated.
• Make your class as private as possible regarding the definition of properties and methods. Use the minimum public properties and functions necessary. For instance, common public functions are only the constructor and global computations, while public properties are usually output variables that another class needs when composed with the former.