Coding Conventions - galacticusorg/galacticus GitHub Wiki
The following are coding conventions employed in Galacticus' source code.
Variable names
- Variable names use
camelCase
form; - Variable names should be descriptive,
massStellarDisk
is preferred overm
, ormass
for example;
Matching parameter names
- For variables which are set via a parameter, the internal variable name should match the parameter name. (This allows automatic handling of the creation of descriptor functions). In some cases this is not possible if the parameter name matches the name of a method of the class. For example, the
stellarFeedbackOutflowsPowerLaw
class has a methodvelocityCharacteristic
, and also reads a parameter of this name. In such cases the internal variable name should match the parameter name with a_
suffix. This convention allows such variables to be correctly included in the creation of descriptor functions.
Function classes
functionClass
objects are the primary object class used within Galacticus to represent physical processes and other actors.
Formatting
Variable declarations
- Only two variables per line, use continuation lines for more than two variables, i.e. instead of:
logical , intent( out) :: diskRequired, spheroidRequired, radiusVirialRequired, radiusScaleRequired
write
logical , intent( out) :: diskRequired , spheroidRequired , &
& radiusVirialRequired, radiusScaleRequired
Comments
LaTeX vs. Unicode
Comments inside !!{ !!}
sections should use LaTeX syntax (as they are directly rendered into the documentation which is built using LaTeX. Comments outside of these sections should avoid LaTeX syntax where possible, and instead use unicode symbols. For example, use ! km s¯¹
instead of ! km s^{-1}
.
Citations
Where relevant, include citations to papers in comments. For example, before a line implementing an equation from a paper, include a comment line:
! Critical mass model from Author1 & Author2 (2015; http://.......).
It is preferred that the URL be to the NASA ADS entry for the paper if possible.
Citations should also be given in class description elements also - for example if a class implements a model from a specific paper cite that paper in the description, e.g.:
<nodeOperator name="nodeOperatorFunPhysics">
<description>A node operator that implements some fun physics. Based on the model of \cite{funPhysicsPaper}.</description>
</nodeOperator>
and include a bibliography entry in docs/Galacticus.bib
for this paper (this will then be automatically included into the documentation). Note that the preferred way to add entries to the bibliography is to first add the relevant NASA ADS record to the Galacticus Zotero library, and then export from there into docs/Galacticus.bib
.
Constants
- Floating point constants should be written as explicitly double precision, so
7.0
should be7.0d0
for example. - Avoid arbitrary numbers appearing in the code, e.g. instead of
3.2408d-14
, define a variable that has a descriptive name, e.g.:
double precision, parameter :: importantPhysicalConstant=3.2408d-14`
so that it is obvious to what this number refers.