Deprecated ‐ CatSim programming “style guide” - xcist/documentation GitHub Wiki

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.

  1. Comments

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

  2. Dead code

    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.

  3. Code replication

    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.

  4. Whitespace in code

    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;

  5. Variable names

    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

  6. Function names

    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.
⚠️ **GitHub.com Fallback** ⚠️