 |
7.3
general documentation
|
|
|
7.3
general documentation
|
|
Keep the style consistent !
This rule should be observed above all others. The coding style in code_saturne has evolved over the years, but unless you are ready to update a whole file to a more current style (in which case the other guidelines should be followed), try to remain consistent with the style in the current file.
For new files, use recently recently updated or reference examples, such as src/base/cs_field.c and src/base/cs_field.h for C, src/base/field.f90 for Fortran modules, or src/base/covofi.f90 for other Fortran files.
If you consider your preferred coding style is better than the one used is superior in some manner to the one used, suggestions are welcome, and may lead to evolutions in the current style if the arguments are convincing, but remember that an inconsistent style is more time-consuming and difficult to read and understand.
Developers trying to follow a consistent style should expect help and counseling when they have questions, but those whose time is too precious to observe the existing code before providing their own or requesting assistance should understand that this is also true of those whom they expect to read their code.
The following general rules are strongly recommended:
sbin/rmb script can be used to remove trailing white-space and replace tabs with spaces, but this may appear to damage indentation when it is defined with an odd mix of spaces and tabs, so using a good editor in the first place is always preferred.For new developments, prefer C to Fortran, as the code should progressively move to purely C (and maybe C++) code. As many variables and arrays are still accessible only through Fortran modules, this is not always possible, but defining Fortran/C bindings such as in the field.f90 module helps make data accessible to both languages, easing the progressive migration from Fortran to C. Fortran bindings should only be defined when access to C functions or variables from Fortran is required, and may be removed for parts of the code purely handled in C.
Except when adding additional white space to align similar definitions or arguments on several lines, standard English punctuation rules should be followed:
The code_saturne coding style inherits from common conventions, with a few specific additions.
The following presentation rules should be followed:
.h files should have a mechanism to prevent multiple inclusions.The following coding rules are strongly recommended:
static. It it is needed in other files, then it must instead be declared extern' in the matching header file.const type must not be cast into a non-const type.switch construct should have a default clause (which may reduce to assert(0) to check code paths in debug mode, but at least this much must be ensured).const attribute should be used when an array or structure is not modified. Recall that for example const cs_mesh_t *m means that the contents of mesh structure m are not modified by the function, while cs_mesh_t *const m only means that the pointer to m is not modified; const cs_mesh_t *const m means both, but its usage in a function prototype gives no additional useful information on the function's side effects than the first form const cs_mesh_t *m, so that form is preferred, as it does not clutter the code.array[] is preferred to *array, as the array nature of the argument is made more visible.switch construct has no case for a given enumeration value.Try to be consistent regarding line spacing. Use 1 separation line to highlight code blocks, but no more (i.e. avoid 2 successive blank lines). Make the code symmetric also: when a blank line follows an opening brace {, a similar line should precede the matching closing brace }. When no such line is used after an opening brace, none should be used either before the closing brace.
A .clang-format configuration file is available in the top-level source directory, so the clang-format tool may be used to obtain an acceptable presentation. Automated formatting does not exactly follow the above recommendations, but is as close as possible using the available parameters, so can provide a good starting point, though it is not activated automatically to allow for manual fine-tuning.
ANSI C11 or above is required, so C11-specific constructs are allowed, though C++ style comments should be avoided, so as to maintain a consistent style. C99 variable-length arrays should be avoided, as it is not always clear whether they are allocated on the stack or heap, and are an optional feature only (though we could expect that support for those constructs will remain available on general-purpose architectures, and removed only in the embedded space).
Assertions are conditions which must always be verified. Several expanded macro libraries may be available, but a standard C language assertion has the following properties:
NDEBUG macro is defined).Assertions are thus very useful to ensure that conditions which are always expected (and not dependent on program input) are met. They also make code more readable, in the sense that it is made clear that conditions checked by an assertion are always expected, and that not handling other cases is not an programming error or omission.
If a condition may not be met for some program inputs, and not just in case of programmer error, a more complete test and call to an error handler (such as bft_error) is preferred.
The following rules should be followed:
n_elt_groups_.cs_= or BFT_.idx_ or index_ prefix or suffix, while similar arrays using a 1 to n numbering (usually those that may be also used in Fortran code) should be named using a pos_ prefix or suffix.id_ prefix or suffix, while identifiers using a 1 to n numbering (usually those that may be also used in Fortran code) should be named using a num_ prefix or suffix.The following form is preferred for enumerations:
Macros and enumerations related to myclass structures are prefixed by CS_MYCLASS_.
Public functions implementing methods are named cs_*class_method*, while private functions are simply named: class_method and are declared static.
Files containing these functions are named class.c.
Several integer types are found in code_saturne:
cs_lnum_t should be used for local entity (i.e. vertex, face, cell) numbers or connectivity. It is a signed integer, normally identical to int, but a larger size could be used in the future for very large meshes on shared memory machines.cs_gnum_t should be used for global entity numbers, usually necessary only for I/O aspects. It is an unsigned 32 or 64-bit integer, depending on whether the code was configured with the --enable-long-gnum option. Global numbers should always use this type, as for very large meshes, they may exceed the maximum size of a 32-bit integer (2 147 483 648). The choice of unsigned integers is two-fold: it doubles the range of available values, and good compilers will issue warnings when this type is mixed without precaution with the usual integer types. These warnings should be heeded, as they may avoid many hours of debugging.int and size_t should be preferred (for example for loops over variables, probes, or any entity independent of mesh size.In the code_saturne kernel, it is preferable to use base functions provided by the BFT subsystem to the usual C functions, as those logging, exit and error-handling functions will work correctly when running in parallel, and the memory management macros ensure return value checking and allow additional logging.
The array below summarizes the replacements for usual functions:
| Standard C function | code_saturne macro or function | Header |
|---|---|---|
exit | cs_exit | cs_base.h |
exit on error | bft_error | bft_error.h |
printf | bft_printf | bft_printf.h |
printf (to standard logs) | cs_log_printf | cs_log.h |
malloc | BFT_MALLOC | bft_mem.h |
| CS_MALLOC_HD | cs_base_accel.h | |
realloc | BFT_REALLOC | bft_mem.h |
| CS_REALLOC_HD | cs_base_accel.h | |
free | BFT_FREE | bft_mem.h |
| CS_FREE_HD | cs_base_accel.h |
Messages for the user should always be defined in US English in the source code (which avoids using extended characters and the accompanying text encoding issues in source code).
To make future internationalization using a mechanism such as gettext() possible, translatable strings should be encased in a _( ) macro (actually an abbreviation for a call to gettext() if available, which reverts to an empty (identity) macro is internationalization is unavailable or disabled). Strings assigned to variables must be encased in a N_( ) macro (which is an ``empty'' macro, used by the gettext toolchain to determine that those strings should appear in the translation dictionary), and the variable to which such a string is assigned should be encased in the _( ) macro where used.
Note that with UTF-8 type character strings, accented or otherwise extended characters are represented on multiple bytes. The strlen C function will return the string's real size, which may be greater than the number of output columns it uses. The cs_log_strlen function may be used to compute the printable width of a character string, while and cs_log_strpad and cs_log_strpadl may be use to pad a string.
The following coding conventions were applied when the code used Fortran 77, prior to conversion to Fortran 95. Some of them should be updated, as long as we maintain consistency within a given file.
private. This rule has exceptions, such as in modules, in the cs_user_parameters.f90 user file which contains several subroutines (it initially followed the rule, but subroutines were split, while the file was not), and Fortran wrappers for several C functions defined in a single C file are also usually defined in a single source, as they are a consistent whole._ characters, use bind(C) (iso-C bindings) in the Fortran code rather than the obsolete CS_PROCF C macro, as compilers may add extra _ characters for identifiers already containing them, and this can lead to linkage issues.CS_PROCF macro must not be used for new code. ISO C bindings must be used instead.i, j, or k) for local or short loops if this helps make the code concise and readable, but prefer more explicit identifiers whenever the scope is not obvious.do / enddo constructs instead of do / continue.goto constructs where select / case would be more appropriate.write(format, *), or print constructs, to ensure that output is redirected correctly in parallel mode.write(format, nfecra) insteadd and not e to define double-precision floating-point constant definitions. Especially avoid constants with exponents such as e50, which are impossible in single precision (the limit is e38), and may thus not be accepted by "strict" compilers, or worst, lead to run-time exceptions.Fortran 2008 or above is required (to allow for intrinsics such as the gamma function), though the coding style is inherited from Fortan 95.
Interoperability of Fortran and C is possible using the iso_c_bindings Fortran module, but not easy to automate.
Fortran constructs which do not map easily to C using these bindings should be avoided.
It is preferred than new code be written in C rather than in Fortran. Fortran continues to be one of the best supported languages in HPC (with C++ and C), and has some interesting features such as Co-Array Fortran (starting with in Fortran 2008), but...
The core python scripts use a coding style similar to PEP-8 PEP-8. PEP-257 (docstring conventions) is also recommended.
Other parts of the code tend to use a camelCase naming, but should otherwise adhere to the same standards. Moving the to PEP-8 style would be ideal, though to avoid confusion, this should be done in an atomic step for each module.
Documentation of the main code is based on the Doxygen tool, whose documentation may be found on its web site.
Additional pages for the documentation may be found in the source tree, under docs/doxygen. Files containing mostly examaples may use the .h or .dox extension (with .dox preferred for easier identification), and pages which describe general aspects instead of code are preferrably written in Doxygen Markdown (.md extension), as this allows better readability and interoperation with some editors (such as preview, syntax highlighting, ...).
When building the code, remember to often use make html and check the docs/doxygen/doxygen_warn.log file in the build directory for errors and warnings.
When modifying arguments to a function or modifying structures, make sure the special Doxygen comments are kept up to date. In C code, comments may appear both in the C and Fortran parts of the code. Using Doxygen comments in the C code and simplified comments in the headers (see cs_field.c and cs_field.h for example) is recommended, but as this adds to the coding effort, duplicating the headers from the reference C code to the headers is allowed. Recent versions of Doxygen do complain about this, so avoiding duplicates is still desirable.
Private functions or structures should not appear in the documentation (though their arguments should be documented in the source code), so in most source files,
used to mark the end of that section. In most cases, this includes private structures and functions in C code, but could be extended to public function definitions if the .h file header already contains the same Doxygen-formated comments.
1.8.13