coding practices

Parent: Developer

Formatting. The two oce developers use different editors, but with settings that (mostly) produce similar indentation. Rather than list that here, the best advice to contributors is that they look in existing source files.

Efficiency. Expensive (time-consuming or memory-consuming) parts are generally written in high-performance languages. For example, acoustic-Doppler files employ checksums whose computation requires extensive bit-level calculation, so this is done in C. Since the developers are using oce for real-world work, they do not fall into the trap of trying to optimize things that do not matter. For example, section objects tend to contain only 10s or 100s of CTD stations, so there is no problem in looping over these in R, and there is much to be gained, in terms of code readability.

Functionality. The developers focus on important things first. If there is a plot type that is likely to be helpful to a wide variety of users, then that will be the default. If there is a data format that is commonly used, then that is more likely to be handled than one that is rarely used. If there is a method that oceanographers tend to employ, the developers will tend to code that before something that is of only historical interest. The developers mainly focus on things that affect their own work, in the hopes that others will contribute their expertise if oce proves to be lacking in some way.

Graphical choices. oce employs base graphics. Early on in the development, tests were done of ggplot and ggplot2 but they were found to be slow for datasets of the size typical in oceanography. Also, since oce grew out of a research environment, there was no need for the "fancy" graphics provided by ggplot, clear black marks on white background being favoured by technical journals.

Risky-code flags. Any segments of code that are considered risky (e.g. that are making assumptions based on reverse-engineering a file, as opposed to an official file-format documentation) are marked as follows. (It is important to follow this exact format, so that a git grep operation can find the blocks.)

## ----------
## RISKY CODE
## ----------