CatSim was originally developed in a somewhat ad hoc manner, without any formal attempt at consistency in programming style. Clearly, there are many different and entirely valid styles. However, to make it easier to understand and revise the code, an initiative was taken with version 5.1 to improve consistency in programming style. Please attempt to conform to the following.

Rather than a cryptic reminder to yourself, take a minute to write enough information that someone other than you will understand your point.

If you’re editing code, don’t copy it and comment it out, then revise. We have a revision-control system and we can always recover older versions. Commented-out code can be confusing and distracting, especially as it accumulates over time.

It’s a wide standard in programming to avoid replicating the same or similar functionality in multiple places (copy-paste programming). Much replicated m-code was reduced in CatSim 5.2. Please attempt to:

Avoid replicating code

If you need functionality that already exists as part of another function,

1. Create a new function (use the naming conventions below).
2. Move the code you need into your new function.
3. Call the new function from the original place that you moved the code from.
4. Test the original application for identical functionality with your new function.
5. Implement your new code with a call to your new function.
   

If you need functionality that is very similar to what already exists in another function,

1. Do the above.
2. Add your variation to the new function, perhaps with an argument or with a “cfg” variable.
3. Test the original application for identical functionality with your new function (with variation disabled).
4. Implement your new code with a call your new function, with your variation enabled.

Young people: old eyes have a hard time enough time already. Please give us a break. Leave space before and after:

= signs
+ and – operators
comparison operators (e.g. ~=)
“dot” matrix operators (e.g. ./)
: characters (array range delimiters)

Leave space after commas in argument lists (as if writing a sentence).
Some people like not to leave spaces around * and / operators, because this serves as a reminder of order of precedence – this is ok. Similarly, sometimes it’s clearer to not leave spaces around a delimiter. The idea is to make it easy to read, and easy to see the sequence of operations.

Example:
alphas=(double(1:n_modules)-double(n_modules+1)/2.0)*dalpha+offset;

is hard on old eyes. This is better:

alphas = (double(1:n_modules) - double(n_modules+1)/2.0)*dalpha + offset;

In general, it’s better to use verbose names – this can improve readability and document functionality. A common practice is to use simple but unique names when developing (e.g. a1 or xx), then use search-and-replace to document your code with verbose names. Using a too-simple name like i makes it harder to replace with a more meaningful name.

There are a number of commonly-used structures, structure fields, and values for fields in these structures. The names of these structures, and fields of these, are typically all lower case, with underscores between words. However, there is some inconsistency, as sometimes field names use upper case characters; these were all left unchanged. These include:

cfg     contains many configuration parameters for the simulation
src     contains source information
spec    contains spectrum information
det     contains detector information

Examples of structure field names (existing names kept)

cfg.callback_flux
src.corners
det.modcoords
spec.Evec

To set other variables apart from these, we’ve named many variables using the convention that all words begin with upper case, and underscores are used only occasionally. Examples of other variable names:

ViewNumber
SourceRotation
NumberOfMaterials

There are a few different types of functions found in CatSim code:

• Built-in Matlab functions
• Catsim’s Matlab functions
• Catsim’s Matlab functions that are “wrappers” for calls to C functions
• C functions (compiled and part of CatSim’s run-time library)
  

In pre-5.2 versions, as one reviewed the code, it wasn’t obvious which type of function was being called, or what aspect of the model was being affected by the function call. Therefore, we have initiated the following standards. Many m-files have been re-named to conform to this.

• Built-in Matlab functions
  Named by Matlab, typically using all lower case.
  
• Catsim’s Matlab functions
  Begin words with upper case character
  Names begin with component of model that is affected.
  Then, type of projector is identified.
  Then, action is identified.
  Example: Phantom_Analytic_BoundObjects.m
  
• Catsim’s Matlab functions that are “wrappers” for calls to C functions
  Names begin with C_.
  Then, conform to rules for other CatSim Matlab functions.
  Example: C_Phantom_Analytic_SetBoundary.m
  
• C functions
  These are not always consistently or clearly named, but have not been changed.
  All C functions should be called from a clearly named “wrapper” function.
  

Back to Main menu