GSIM - Coding Guidelines

Introduction

At the risk of being pedantic, this page tries to lay out some guidelines for writing code for the gsim project. They are by no means a "be all and end all" set of rules, instead I see them more as suggestions how one may write code that is more robust, easier to read and understand, and hopefully, excutes faster.

Any suggestion that you may have for inclusion or modification of these guidelines are most welcome ! Please, please email me if you have any. You can also edit these pages yourself (/home/holtrop/public_html) and then email me so I won't overwrite your changes by mistake.

Guidlines

1) Comment all your work

Include extra information about what your code does.
Use easy to understand variable and subroutine names.
If you "hard code" numbers, explain what they are,
If you load numbers from BOS, make sure they are explained in the appropriate places (bos declaration) and consider duplicating this in the code.
Include your name ( and email and date of modification)
When updating geometry, consider including the reference number of the drawings you based these modifications on.
Consider adding extra information in these webpages.

Especially in a multi-developer environment like gsim (or recsis for that matter) it is very important to comment your work. Personally, I often find my own code incomprehensible after a couple of years if I don't comment it. This is even more true for reading code that is written by someone else, and even more so if it is something I am not familiar with. You also do yourself a favor by adding your name to these comments. That way you get credit for what you did, and in case someone else disagrees (hopefully a rare occurrence) they will know who to contact before making changes.

2) GEANT Geometry

Try to include new geometry in the existing scheme, so that detectors can be turned off as single units.
Try limiting the number of new named objects by declaring the object with null parameters (in GSVOLU and then dimensioning and positioning them with GSPOSP instead of GSPOS . This way we limit the number of named parts, and generate more efficient code.
If at all possible declare objects as 'ONLY' instead of as 'MANY'. (See the GEANT manual GEOM020) The search algorithm for 'ONLY' objects is much faster. (Any object that does not contain daughter volumes can be declared 'ONLY')

3) Generate Code with efficiency in mind.

Try using already existing code if at all possible. Re-use the rotation matrixes and materials that are already declared in the main initialization. If another detector uses the same material but declares it provately, consider modefying that code to make the definitions in the main initialization and reuse these declarations.
If at all possible, don't copy BOS bank contends to a local array, use the BOS arrays directly. This saves a lot of space, and gsim is too big as is.
Keep loop optimiation in mind. Most compilers can't do loop optimization if a subroutine is called inside the loop. Consider whether it is better to use a subroutine, a cpp macro, or in-lining the code.

4) Consider BOS.

Decide whether the variables you initialize should be gotten from a BOS bank instead of a DATA statement. (In either case, comment it !) Many geometry definitions are currently data statements, and really should have been BOSified.
Decide what information should be exported into the BOS output file.
Decide what information can be made available to the user routines using a BOS bank.

5) Notify the World.

Tell everybody else of your changes by sending mail to class_offline.
Consider adding info to these web pages: mail me, or edit the pages yourself (/home/holtrop/public_html) and then mail me.