Page History

Purpose

The primary goal of DM programming style guides is to improve readability and thereby the understanding, maintainability and general quality of the code. It is impossible to cover every specific situation in a general guide so programmer flexibility in interpreting the guidelines - in the spirit in which they were written - is essential.

Experienced programmers have generally evolved a personal programming style which might have been based on textbook recommendations, other projects' style guides or recognition of the clarity that certain styles obtain. DM developers participated in the creation of the DM style guides; they brought their extensive programming experience into fabricating a uniform style for DM code.

New DM developers should use these guidelines to understand and emulate the coding style adopted by DM. 

Stringency Levels

The guidelines include a rating system which defines the importance that DM assigns to conforming to a specific recommendation.

In the guidelines certain terms have special meaning as follows:

• REQUIRED means that the Rule is an absolute requirement of the specification. The developer needs to petition the DM TCT to acquire explicit approval to contravene the Rule.
• PROHIBITED is the opposite of REQUIRED.

• MUST and SHALL mean that there may exist valid reasons in particular circumstances to ignore a particular Rule, but the full implications must be understood and carefully weighed before choosing a different course. The developer needs to petition the lead developer to acquire explicit approval to contravene the Rule.
• MUST NOT and SHALL NOT are their respective opposites.

• SHOULD, RECOMMENDED and MAY mean that there are valid reasons in particular circumstances to ignore a particular Rule. The developer is expected to personally consider the full implications before choosing a different course.
• SHOULD NOT, NOT RECOMMENDED and MAY NOT are their opposites.

Deviating from the DM Style

The guides provide the rationale supporting each of their recommendations. Consider that rationale before choosing to deviate from the DM coding style. Be aware that some recommendations also demonstrate 'best-practice' techniques used to avoid introducing programming errors; 'best-practice' use is noted.

Coding consistency is very important but sometimes the style guide doesn't apply either due to lack of a definitive rule or the circumstances of the specific code segment logically dictate otherwise. When in doubt, use your best judgment or ask the lead developer.

Here are two plausible reasons to break a particular rule:

• When applying the rule would make the code less readable, even for someone who is used to reading code that follows the rules.
• To be consistent with surrounding code that also breaks it (maybe for historic reasons) -- although this is also an opportunity to clean up someone else's mess.

Transitioning from the R&D Phase to Construction

During the early R & D phases of LSST development, the coding guidelines are more advisory than regulatory. However, by the final Data Challenge prior to Construction, DM is expected to demonstrate to the funding agencies compliance to the Coding Style Guidelines to within some tolerance level.

DM Coding Style Checkers

Even though the developer has substantial leeway when following the DM Coding Style Guidelines, the DM Coding Style Checkers will check compliance and report deviations. In situations where the developer has considered the options and decided to deviate from the DM style, the developer may flag the deviation in the source so that it is not reported as a compliance error. This extra step ensures that the developer recognizes the deviation and has intentionally accepted it.