Coding style - nrc-cnrc/EGSnrc GitHub Wiki

Programmers all have their preference when it comes to coding style: indentation levels, where to put delimiters, how to align code blocks, white space usage, etc. However, in a collaborative environment, a style standard prevents polluting the commit history with ongoing format changes that are irrelevant to the logic of the code.

C++

The most important style aspects to adhere to when editing EGSnrc C++ files are:

  1. Use .cpp and a .h extensions for source and header files, respectively.
  2. Remove end-of-line white space (set your editor to curb trailing spaces upon saving)
  3. Indent with 4 spaces; avoid tab characters (except when required, such as in Makefiles)
  4. Retain the file heading, unmodified, except to add contributor names.
  5. Leave the first line blank if possible (e.g., bash scripts require a leading #!/bin/bash line)
  6. Limit line width to 80 characters, as much as possible (except end of line comments)
  7. Comment the code in the source file, but explain changes in the commit message
  8. Prune obsolete code blocks instead of commenting them out: they persist in the git history

We standardized the C++ style of the egs++ source files in commit 574f13e with the [Artistic Style] version 3.1 (http://astyle.sourceforge.net/) utility (invoked with the astyle command) using the following options, saved in $HEN_HOUSE/scripts/egs_style_standard for convenience:

--convert-tabs              # convert all tabs to spaces
--indent=spaces=4           # indent is 4 spaces
--style=attach              # attach opening bracket at end of line
--unpad-paren               # remove extra space padding around parenthesis on the inside and outside
--pad-header                # space padding between a header and the following parenthesis
--align-pointer=name        # attach pointer or reference to variable name
--break-closing-brackets    # breaks closing headers from their immediately preceding closing brackets
--add-brackets              # add brackets to unbracketed one line conditional statements
--indent-preproc-block      # indent preprocessor blocks

Hence after creating or modifying a source file filename.cpp and its header file filename.h, for example, you can normalize their style with the command:

astyle --options=$HEN_HOUSE/scripts/egs_style_standard filename.cpp filename.h

To normalize the coding style on an entire directory, use the --recursive argument, for example:

cd $HEN_HOUSE/egs++
astyle --recursive --options=$HEN_HOUSE/scripts/egs_style_standard "*.h" "*.cpp"

Note that by default astyle also removes trailing end-of-line whitespace. The 80-character text width is not enforced by egs_style_standard.

This default style is not always ideal, e.g., it adds braces and line returns to all conditionals, which can make consecutive if one-liners more difficult to understand. In such cases you may elect to disable formatting for code sections that become less readable after processing through astyle.

End-of-line whitespace

You should set your editor to remove end-of-line (EOL) whitespace upon saving, to prevent polluting the file history with irrelevant changes. All EOL whitespace was removed from the EGSnrc repository in pull request #237. To list which files contain EOL whitespace in a directory, use:

grep -ERl -I '\s+$' .

If you have ripgrep installed, the following equivalent command is at least an order of magnitude faster:

rg -l '\s+$' .

To remove EOL whitespace in all files in a directory, use:

# bash shell
for f in $(grep -ERl -I '\s+$' .); do
    echo $f;
    sed -i -e's/[:space:](/nrc-cnrc/EGSnrc/wiki/:space:)*$//' $f;
done

# fish shell
for f in (grep -ERl -I '\s+$' .)
    echo $f
    sed -i -e 's/[:space:](/nrc-cnrc/EGSnrc/wiki/:space:)*$//' $f
end

In case a directory contain data files with required trailing EOL whitespace, then pipe the grep outputs above to exclude this directory. For example:

grep -ERl -I '\s+$' | grep -Ev '^HEN_HOUSE/spectra/lnhb/'