General Information

Before adding a new code to the CVS repository, any Maker and or code needs to be peer reviewed. Please, consult the STAR coding and naming standards pages before even starting to design a new maker or code. This document will help you shape, through basic guidelines, your code structure and layout.

Code peer review is a process by which members of the collaboration, code developers themselves, are asked to review your code as per its fitness to be included in the standard STAR framework. We hope this process will bring to developers of maker useful inputs as per the reuse of existing classes, the integration of the code within a chain, its interaction with our IO model etc ...

The task of the reviewers

The basic peer review should address the following issues :

1. General coding style and standard Naming convention
   • Naming convention must be followed
   • Classes must have destructor / constructor
   • Access to data members must be through access methods
   • Global variables usage (should be avoided, suggestions if used)
   • Constants, variables, method should have self-explanatory names
   • ...
   There are more guidelines in the STAR coding and naming standards document the reviewers should consider. Reviewers should send their recommendations and specific advices if standards are broken.
2. The code layout i.e. The directory structure (is the documentation in the proper doc/ directory, the macros in the macros/ directory etc ...)
3. The presence of documentation and if it was sufficient to understand what the intent of code was. Complete lack of documentation should be considered as a show stopper for the review.
4. Code general suggestions and comments :
   • issues related to re-use of existing base classes
   • merging with existing or similar sub-systems developed classes etc ...).
   • Hardwired constants and suggestions (for example, a database approach for calibration constants, if applicable, is a good suggestion).
   • In case of simulation makers, the reviewers should pay particular attention to the GEANT geometry and how it relates to the reconstruction code and, for a sub-system in development mode, the geometry flexibility.
5. Is the algorithm sound, any missing parts / improvements suggestions, approaches the developer should try or consider in future.
6. General comments on readiness of the code to be inserted.
7. The almost last and one of the mandatory requirements is for the code to compile (hum ... it should be never knows ...) and this, on at least the preferred platform (a code will NOT be added if it fails this basic requirement) but preferably the two supported platforms.
8. Finally, can you run the code (always good to compile but if it crashes, it is not ready)? Does it seem to provide meaningful results within the provided example and/or instructions?

There are at least two peer reviewers per new code. The peer reviewers should agree that the code is important, should be included in the set of makers, is ready for deployment and, if there are more work to be done, should clearly state what is required in their views for the code to be functional. Suggestions for future improvements must be clearly stated and a road map for implementation offered to the developer . The reviewers should also explicitly sign-off on the code.

As a last note, a peer review is advisory to the STAR Software & Computing leader. In case of disagreement, a summary and ruling will be sent to the person reviewed (and reviewers) indicating the changes to be made. After a peer review is closed, a notice will be sent to starsoft so all (core team as well as other coordinators) are informed of the new incoming code.

Preparing your code for a peer review

You should first make sure that your code will pass the above criteria. Your code must be available to the reviewers from a public space. Please, check protection (g+r in NFS space) or acl (star rl in AFS).

When you feel ready to have your code reviewed, send an Email to STAR Software & Computing leader requiring a review process to take place along with a quick description of your maker / code and the status of your code (still in development mode, final version, why you would like to have it included to the official repository, etc ...). Avoid development code at all cost unless clear justifications.

For a meaningful review, please provide instructions (macro or chain) on how to run your code with all arguments specified (least work for the reviewers, should work as instructed). Possibly, how to verify the results are correct in case your code deals with Physics-ready structures is an asset. At minimum, we require the code compiles & run and that reviewers understand its purpose and documentation is adequate.

Members of the collaboration will be asked to take on this task within a day or two. Comments, answers and action items must be sent and communicated via Emails to all members of the peer review committee (they will appear in the initial Email starting the review process). After all reviewers have sent their contributions, you will be informed of the the critical items to be taken care off and an expected / suggested time frame for the insertion of the new code in our library.

Past peer reviews