Style Guide

The purpose of this document is to describe the conventions for writing kite project code.

Organization

For guidelines on where files and folders should be located in the file tree please see the Directory Structure page.

Units and compositions

Simulink files in this software are categorized as either units, or compositions. Roughly speaking, a unit is the smallest block of Simulink code that actually performs any operation(s) on a signal. Conversely, compositions, are files consisting of configurations of units. Compositions manage the arrangement and interconnection of units, but they do not perform any math or logic. Note that compositions often contain other compositions.

Examples of blocks commonly found in compositions: selector, bus selector, mux, demux, bus creator, units, other compositions. Examples of blocks commonly found in units, gain, multiplication, integrator, etc.

Both units and compositions should be saved in a Simulink library file.

File Naming Conventions

File names should be descriptive and should include one of the following suffixes as appropriate.

• _ul = "unit library" | descriptiveName_ul.slx
• _cl = "composition library" | descriptiveName_cl.slx
• _cm = "composition model" | descriptiveName_cl.slx
• _init = "initialization" | descriptiveName_init.m
• _th = "test harness" | descriptiveName_th.slx
• _ts = "test script" | descriptiveName_ts.slx
• _prrn = "pre-run" | descriptiveName_prrn.slx

Variable Naming Conventions

Variable names should generally be of the form prefix_descriptiveName_units.extnsion.
The prefix should relate to where in the model the variable is used. For example, ctrl_x is a variable called x that is used in the controller and plnt_x is a variable called x that is used in the plant. There are no hard rules for abbreviation, but effort should be may to continue conventions already present in the code (e.g. ctrl = "controller" and plnt = "plant").
The descriptiveName should, within reason, enable identification of the referent property that is being represented by the variable. Use camel case to separate words in the descriptive name. Whenever possible, include the SI units as a suffix if they are explicitly or implicitly assumed in the model.

Bad Variable Name	Bad Variable Name	OK Variable Name
omegaX	theXComponentOfTheAngularVelocityOfTheVehicleBodyFrameWithRespectToTheInertialFrame	xAngVelOB_perS

Filename Suffixes

_ul

the smallest bit of stand-alone code, saved as a simulink library. You should be able to take this and drop it into a stand-alone model to test it.

_cl

a collection of units all hooked up to eachother, saved as a simulink library. You can also take this and drop it into a standalone model to test it. However, a lot of the time these reach such a high level of complexity that there's a million inputs and outputs, so that's not aways possible. However, for small compositions (containing only a few units), it may be possible.

_cm

the highest level model, containing all the composition libraries that comprise the model. This is the only file that actually has model configuration parameters associated with it, so it's the only thing that you can actually run.

_init

the script (NOT FUNCTION), that you have to run to get all the right variables into the base workspace so that your model will run. These should directly parallel the naming structure of the compositions and units. So say we have a composition library called "controller_cl.slx". The file "controller_init.m" will be a script that sets the values of variables and parameters used by controller_cl.slx, in the base workspace (for example, controller gains).

_th

as alluded to above, you often want to take individual units or compositions and test them alone, in isolation. This is a simulink model used for that purpose. The description should parallel whatever unit or composition that you want to test. For examble, "gain_th.slx" could be a simulink model where you want to test the unit in the unit library "gain_ul.slx".

_ts

this is a script used to set parameters and call the test harness model.

_prrn

this is a script that should be run before running a simulation. Usually, this initializes the variables needed for whatever model variant is active.