Prof. Voyles' Coding Style

Coding Style

C Conventions (Python, too!)

Source files should be broken into manageable pieces with meaningful names. Every source file must have a comment block at the top identifying the name of the file, its contents, and revision history. (See Matlab exception, below.) A sample is (copyright is an optional element):

/* --- TRAJQ.C       Version 1.1
   --- This module continuously cycles through a trajectory specified by a series of 
   --- via points. Each via point consists of 6 joint values (radians), speed value (in percent), 
   --- and delay value (in seconds).
   ---
   --- Copyright 2001, Mark V Automation Corp.
   ---
   --- 02/28/01 RMV     Initial coding. Copied from moveq for TerminatorBot.
   --- 03/05/01 RMV	Seems to work. v1.0
   --- 05/01/01 RMV	Added support for specified delays between via points. v1.1
   ---
   --- */

Different languages have different syntax, but the idea is the same.

In addition, all functions will have a comment block immediately above it, describing what it does and any arguments and return values. Use frequent comments throughout the code that add meaningful information. Never add the following type of meaningless comments:

  a = 5;	/* assign 5 to variable a */

This comment doesn't add any information! Instead, do something like this:

#define	DEFAULT_GOAL_THETA	5

  Qdesired = DEFAULT_GOAL_THETA; 	/* initialize theta desired prior to power up */

"Qdesired" is a more meaningful variable name and by defining a default goal value, you can refer to it repeatedly and only need to change it in one place.

Comment all source files and treat all code as if it will exist forever! Never assume test code or prototype code is not important or can be commented later. I may perform surprise audits on your working code and if it is not commented, you will lose points.

Some coding conventions we will follow:

Never put executable code in header files (*.h files).
Header files should be specific to a source file to promote portability.
#define constants are always in ALL-CAPS
Variable names are descriptive, start with a small letter (unless other conventions prevail), and use caps only to delimit words (lower camel casing): motorSpeed
Class names are also descriptive, start with an upper letter (unless other conventions prevail), and use caps only to delimit words (upper camel casing): MotorController
Global variables, when justified, must end in "G": motorPositionG
User-defined types must end in "_t": typedef void * pointer_t

MatLab Conventions

MatLab coding style is similar to C coding style. Some additions:

Create functions whenever possible (not straightline code scripts). Scripts have value, but are dependent on context.
Always, always, always include a "help" block at the beginning of your function code. This should include a description of the function, the calling convention (function name, arguments and outputs), and descriptions of the inputs/outputs. Include any default values or optional parameters. (For class, I recommend your name, as well.)
Use upper case variables for matrices, lower case for vectors (Fmax and fmax)
Include liberal and meaningful comments to explain what you are doing and why

To include a help block, put contiguous comments at the beginning of your function:


function Torque = myFunction(Force)
%%%	Torque = myFunction(Force, vizFlag)
%%%
%%%	This function computes the torque at all the joints of the PUMA 560 manipulator, given the desired force at the 
%%%		end effector. Gravity is considered. This is dependent on the Jacobian, which is computed internally.
%%%
%%%	Force - vector or optional matrix of generalized forces at the end effector: [Fx, Fy, Fz, Tx, Ty, Tz] in row-vector form.
%%%		  If multiple row-vectors are provided, the program steps through each one.
%%%	vizFlag - optional flag that displays a graph of the force vector if non-zero. (default is zero)
%%%
%%%	Torque - vector of torques of the six joints of the manipulator: [T1, T2, T3, T4, T5, T6]. If Force is a matrix of 
%%%		   row-vectors, then Torque will have an equal number of row-vectors.

%%%	This comment is not part of the help as it is not contiguous.
%	Good place for revision history, etc.

NOTE: If you put a comment block at the very top of your file for a ".m" file, it will appear as your "help". So, the filename and revision history, as noted under "C Conventions", should not preempt the help. (You should always test functionality and "help" is no different!)

Prof. Voyles' Home Page

Last modified on: September 18, 2019