From 5c32d86770e80d3f2d56f302622d2b2bc168bd1d Mon Sep 17 00:00:00 2001 From: Sterling Harper Date: Wed, 9 Aug 2017 12:16:19 -0400 Subject: [PATCH 1/4] Update style guide and add C++ style --- docs/source/devguide/index.rst | 1 - docs/source/devguide/structures.rst | 155 ----------------------- docs/source/devguide/styleguide.rst | 184 +++++++++++++++++++++------- 3 files changed, 142 insertions(+), 198 deletions(-) delete mode 100644 docs/source/devguide/structures.rst diff --git a/docs/source/devguide/index.rst b/docs/source/devguide/index.rst index 4dc1b2c74c..1a8252383c 100644 --- a/docs/source/devguide/index.rst +++ b/docs/source/devguide/index.rst @@ -12,7 +12,6 @@ as debugging. :numbered: :maxdepth: 3 - structures styleguide workflow user-input diff --git a/docs/source/devguide/structures.rst b/docs/source/devguide/structures.rst deleted file mode 100644 index 15777f6065..0000000000 --- a/docs/source/devguide/structures.rst +++ /dev/null @@ -1,155 +0,0 @@ -.. _devguide_structures: - -=============== -Data Structures -=============== - -The purpose of this section is to give you an overview of the major data -structures in OpenMC and how they are logically related. A majority of variables -in OpenMC are `derived types`_ (similar to a struct in C). These derived types -are defined in the various header modules, e.g. src/geometry_header.F90. Most -important variables are found in the `global module`_. Have a look through that -module to get a feel for what variables you'll often come across when looking at -OpenMC code. - --------- -Particle --------- - -Perhaps the variable that you will see most often is simply called ``p`` and is -of type(Particle). This variable stores information about a particle's physical -characteristics (coordinates, direction, energy), what cell and material it's -currently in, how many collisions it has undergone, etc. In practice, only one -particle is followed at a time so there is no array of type(Particle). The -Particle type is defined in the `particle_header module`_. - -You will notice that the direction and angle of the particle is stored in a -linked list of type(LocalCoord). In geometries with multiple :ref:`universes`, -the coordinates in each universe are stored in this linked list. If universes or -lattices are not used in a geometry, only one LocalCoord is present in the -linked list. - -The LocalCoord type has a component called cell which gives the index in the -``cells`` array in the `global module`_. The ``cells`` array is of type(Cell) -and stored information about each region defined by the user. - ----- -Cell ----- - -The Cell type is defined in the `geometry_header module`_ along with other -geometry-related derived types. Each cell in the problem is described in terms -of its bounding surfaces, which are listed on the ``surfaces`` component. The -absolute value of each item in the ``surfaces`` component contains the index of -the corresponding surface in the ``surfaces`` array defined in the `global -module`_. The sign on each item in the ``surfaces`` component indicates whether -the cell exists on the positive or negative side of the surface (see -:ref:`methods_geometry`). - -Each cell can either be filled with another universe/lattice or with a -material. If it is filled with a material, the ``material`` component gives the -index of the material in the ``materials`` array defined in the `global -module`_. - -------- -Surface -------- - -The Surface type is defined in the `geometry_header module`_. A surface is -defined by a type (sphere, cylinder, etc.) and a list of coefficients for that -surface type. The simplest example would be a plane perpendicular to the xy, yz, -or xz plane which needs only one parameter. The ``type`` component indicates the -type through integer parameters such as SURF_SPHERE or SURF_CYL_Y (these are -defined in the `constants module`_). The ``coeffs`` component gives the -necessary coefficients to parameterize the surface type (see -:ref:`surface_element`). - --------- -Material --------- - -The Material type is defined in the `material_header module`_. Each material -contains a number of nuclides at a given atom density. Each item in the -``nuclide`` component corresponds to the index in the global ``nuclides`` array -(as usual, found in the `global module`_). The ``atom_density`` component is the -same length as the ``nuclides`` component and lists the corresponding atom -density in atom/barn-cm for each nuclide in the ``nuclides`` component. - -If the material contains nuclides for which binding effects are important in -low-energy scattering, a :math:`S(\alpha,\beta)` can be associated with that -material through the ``sab_table`` component. Again, this component contains the -index in the ``sab_tables`` array from the `global module`_. - -------- -Nuclide -------- - -The Nuclide derived type stores cross section and interaction data for a nucleus -and is defined in the `ace_header module`_. The ``energy`` component is an array -that gives the discrete energies at which microscopic cross sections are -tabulated. The actual microscopic cross sections are stored in a separate -derived type, Reaction. An arrays of Reactions is present in the ``reactions`` -component. There are a few summary microscopic cross sections stored in other -components, such as ``total``, ``elastic``, ``fission``, and ``nu_fission``. - -If a Nuclide is fissionable, the prompt and delayed neutron yield and energy -distributions are also stored on the Nuclide type. Many nuclides also have -unresolved resonance probability table data. If present, this data is stored in -the component ``urr_data`` of derived type UrrData. A complete description of -the probability table method is given in :ref:`probability_tables`. - -The list of nuclides present in a problem is stored in the ``nuclides`` array -defined in the `global module`_. - ----------- -SAlphaBeta ----------- - -The SAlphaBeta derived type stores :math:`S(\alpha,\beta)` data to account for -molecular binding effects when treating thermal scattering. Each SAlphaBeta -table is associated with a specific nuclide as identified in the ``zaid`` -component. A complete description of the :math:`S(\alpha,\beta)` treatment can -be found in :ref:`sab_tables`. - ---------- -XsListing ---------- - -The XsListing derived type stores information on the location of an ACE cross -section table based on the data in cross_sections.xml and is defined in the -`ace_header module`_. For each ```` you see in cross_sections.xml, -there is a XsListing with its information. When the user input is read, the -array ``xs_listings`` in the `global module`_ that is of derived type XsListing -is used to locate the ACE data to parse. - --------------- -NuclideMicroXS --------------- - -The NuclideMicroXS derived type, defined in the `ace_header module`_, acts as a -'cache' for microscopic cross sections. As a particle is traveling through -different materials, cross sections can be reused if the energy of the particle -hasn't changed. The components ``total``, ``elastic``, ``absorption``, -``fission``, and ``nu_fission`` represent those microscopic cross sections at -the current energy of the particle for a given nuclide. An array ``micro_xs`` in -the `global module`_ that is the same length as the ``nuclides`` array stores -these cached cross sections for each nuclide in the problem. - ---------------- -MaterialMacroXS ---------------- - -In addition to the NuclideMicroXS type, there is also a MaterialMacroXS derived -type, defined in the `ace_header module`_ that stored cached *macroscopic* cross -sections for the current material. These macroscopic cross sections are used for -both physics and tallying purposes. The variable ``material_xs`` in the `global -module`_ is of type MaterialMacroXS. - - -.. _derived types: http://nf.nci.org.au/training/FortranAdvanced/slides/slides.025.html -.. _global module: https://github.com/mit-crpg/openmc/blob/master/src/global.F90 -.. _particle_header module: https://github.com/mit-crpg/openmc/blob/master/src/particle_header.F90 -.. _geometry_header module: https://github.com/mit-crpg/openmc/blob/master/src/geometry_header.F90 -.. _constants module: https://github.com/mit-crpg/openmc/blob/master/src/constants.F90 -.. _material_header module: https://github.com/mit-crpg/openmc/blob/master/src/material_header.F90 -.. _ace_header module: https://github.com/mit-crpg/openmc/blob/master/src/ace_header.F90 diff --git a/docs/source/devguide/styleguide.rst b/docs/source/devguide/styleguide.rst index 936f0c8388..e2b3de5c3d 100644 --- a/docs/source/devguide/styleguide.rst +++ b/docs/source/devguide/styleguide.rst @@ -8,35 +8,50 @@ In order to keep the OpenMC code base consistent in style, this guide specifies a number of rules which should be adhered to when modified existing code or adding new code in OpenMC. -------- -Fortran -------- +--------------- +Fortran and C++ +--------------- -General Rules +Miscellaneous ------------- -Conform to the Fortran 2008 standard. - -Make sure code can be compiled with most common compilers, especially gfortran -and the Intel Fortran compiler. This supercedes the previous rule --- if a -Fortran 2003/2008 feature is not implemented in a common compiler, do not use -it. +Make sure code can be compiled with most common compilers, especially the GCC +and Intel compilers. This supersedes the rules about standards---if a Fortran +2003/2008 feature is not implemented in a common compiler then do not use it. Do not use special extensions that can be only be used from certain compilers. -In general, write your code in lower-case. Having code in all caps does not -enhance code readability or otherwise. - Always include comments to describe what your code is doing. Do not be afraid of using copious amounts of comments. -Use <, >, <=, >=, ==, and /= rather than .lt., .gt., .le., .ge., .eq., and .ne. - Try to keep code within 80 columns when possible. -Don't use ``print *`` or ``write(*,*)``. If writing to a file, use a specific -unit. Writing to standard output or standard error should be handled by the -``write_message`` subroutine or functionality in the error module. +Don't use ``print *``, ``write(*,*)``, ``fprintf()``, or ``std::cout``. If +writing to a file, use a specific unit. Writing to standard output or standard +error should be handled by the ``write_message`` subroutine or functionality in +the error module. + +Naming +------ + +In general, write your code in lower-case. Having code in all caps does not +enhance code readability or otherwise. + +Module names should be lower-case with underscores if needed, e.g. +``xml_interface``. + +Class names should be CamelCase, e.g. ``HexLattice``. + +Functions and subroutines (including type-bound methods) should be lower-case +with underscores, e.g. ``get_indices``. + +Local variables, global variables, and type attributes should be lower-case +with underscores (e.g. ``n_cells``) except for physics symbols that are written +differently by convention (e.g. ``E`` for energy). + +Constant (parameter or const) variables should be in upper-case with +underscores, e.g. ``SQRT_PI``. These should usually be defined in the +constants.F90 module. Procedures ---------- @@ -53,28 +68,17 @@ Variables --------- Never, under any circumstances, should implicit variables be used! Always -include ``implicit none`` and define all your variables. +include ``implicit none`` in Fortran source code and define all your variables. -Variable names should be all lower-case and descriptive, i.e. not a random -assortment of letters that doesn't give any information to someone seeing it for -the first time. Variables consisting of multiple words should be separated by -underscores, not hyphens or in camel case. - -Constant (parameter) variables should be in ALL CAPITAL LETTERS and defined in -in the constants.F90 module. - -32-bit reals (real(4)) should never be used. Always use 64-bit reals (real(8)). +32-bit reals (``real(4)`` and ``float``) should never be used. Always use 64-bit +reals (``real(8)`` and ``double``). For arbitrary length character variables, use the pre-defined lengths -MAX_LINE_LEN, MAX_WORD_LEN, and MAX_FILE_LEN if possible. - -Do not use old-style character/array length (e.g. character*80, real*8). +``MAX_LINE_LEN``, ``MAX_WORD_LEN``, and ``MAX_FILE_LEN`` if possible. Integer values being used to indicate a certain state should be defined as named constants (see the constants.F90 module for many examples). -Always use a double colon :: when declaring a variable. - Yes: .. code-block:: fortran @@ -92,20 +96,12 @@ allocation instead. Use allocatable variables instead of pointer variables when possible. Shared/Module Variables -+++++++++++++++++++++++ +----------------------- Always put shared variables in modules. Access module variables through a ``use`` statement. Always use the ``only`` specifier on the ``use`` statement except for variables from the global, constants, and various header modules. -Never use ``equivalence`` statements, ``common`` blocks, or ``data`` statements. - -Derived Types and Classes -------------------------- - -Derived types and classes should have CamelCase names with words not separated -by underscores or hyphens. - Indentation ----------- @@ -158,6 +154,110 @@ each side. Do not leave trailing whitespace at the end of a line. +---------------- +Fortran-Specific +---------------- + +Conform to the Fortran 2008 standard. + +Use <, >, <=, >=, ==, and /= rather than .lt., .gt., .le., .ge., .eq., and .ne. + +Do not use old-style character/array length (e.g. character*80, real*8). + +Always use a double colon :: when declaring a variable. + +Never use ``equivalence`` statements, ``common`` blocks, or ``data`` statements. + +------------ +C++-Specific +------------ + +Miscellaneous +------------- + +Conform to the C++11 standard. + +Always use C++-style comments (``//``) as opposed to C-style (``/**/``). (It +is more difficult to comment out a large section of code that uses C-style +comments.) + +Header files should always use include guards with the following style: + +.. code-block:: C++ + + #ifndef MODULE_NAME_H + #define MODULE_NAME_H + ... + content + ... + #endif // MODULE_NAME_H + +Do not use using-directives e.g. ``using namespace foobar;`` + +Do not use C-style casting. Always use the C++-style casts ``static_cast``, +``const_cast``, or ``reinterpret_cast``. + +Curly braces +------------ + +For a function definition, the opening brace should be on the same line as the +end of the function definition. The closing brace should be on its own line. +If the entire function fits on one line, then the closing brace can be on the +same line. e.g.: + +.. code-block:: C++ + + return_type function(type1 arg1, type2 arg2) { + content(); + } + + return_type + function_with_many_args(type1 arg1, type2 arg2, type3 arg3, + type4 arg4) { + content(); + } + + int return_one() {return 1;} + +For a conditional, the opening brace should be on the same line as the end of +the conditional statement. If there is a following ``else if`` or ``else`` +statement, the closing brace should be on the same line as that following +statement. Otherwise, the closing brace should be on its own line. A one-line +conditional can have the closing brace on the same line or it can omit the +braces entirely e.g.: + +.. code-block:: C++ + + if (condition) { + content(); + } + + if (condition1) { + content(); + } else if (condition 2) { + more_content(); + } else { + further_content(); + } + + if (condition) {content()}; + + if (condition) content(); + +For loops similarly have an opening brace on the same line as the statement and +a closing brace on its own line. One-line loops may have the closing brace on +the same line or omit the braces entirely. + +.. code-block:: C++ + + for (int i = 0; i < 5; i++) { + content(); + } + + for (int i = 0; i < 5; i++) {content();} + + for (int i = 0; i < 5; i++) content(); + ------ Python ------ From 110684619d5c3825ddb1acfe764e8793f8e67565 Mon Sep 17 00:00:00 2001 From: Sterling Harper Date: Tue, 12 Dec 2017 19:27:16 -0500 Subject: [PATCH 2/4] Separate Fortran and C++ info in the styleguide --- docs/source/devguide/styleguide.rst | 96 +++++++++++++++++------------ 1 file changed, 57 insertions(+), 39 deletions(-) diff --git a/docs/source/devguide/styleguide.rst b/docs/source/devguide/styleguide.rst index e2b3de5c3d..4bba8f4c01 100644 --- a/docs/source/devguide/styleguide.rst +++ b/docs/source/devguide/styleguide.rst @@ -8,28 +8,32 @@ In order to keep the OpenMC code base consistent in style, this guide specifies a number of rules which should be adhered to when modified existing code or adding new code in OpenMC. ---------------- -Fortran and C++ ---------------- +------- +Fortran +------- Miscellaneous ------------- -Make sure code can be compiled with most common compilers, especially the GCC -and Intel compilers. This supersedes the rules about standards---if a Fortran -2003/2008 feature is not implemented in a common compiler then do not use it. +Conform to the Fortran 2008 standard. + +Make sure code can be compiled with most common compilers, especially gfortran +and the Intel Fortran compiler. This supercedes the previous rule --- if a +Fortran 2003/2008 feature is not implemented in a common compiler, do not use +it. Do not use special extensions that can be only be used from certain compilers. Always include comments to describe what your code is doing. Do not be afraid of using copious amounts of comments. +Use <, >, <=, >=, ==, and /= rather than .lt., .gt., .le., .ge., .eq., and .ne. + Try to keep code within 80 columns when possible. -Don't use ``print *``, ``write(*,*)``, ``fprintf()``, or ``std::cout``. If -writing to a file, use a specific unit. Writing to standard output or standard -error should be handled by the ``write_message`` subroutine or functionality in -the error module. +Don't use ``print *`` or ``write(*,*)``. If writing to a file, use a specific +unit. Writing to standard output or standard error should be handled by the +``write_message`` subroutine or functionality in the error module. Naming ------ @@ -49,8 +53,8 @@ Local variables, global variables, and type attributes should be lower-case with underscores (e.g. ``n_cells``) except for physics symbols that are written differently by convention (e.g. ``E`` for energy). -Constant (parameter or const) variables should be in upper-case with -underscores, e.g. ``SQRT_PI``. These should usually be defined in the +Constant (parameter) variables should be in upper-case with underscores, e.g. +``SQRT_PI``. If they are used by more than one module, define them in the constants.F90 module. Procedures @@ -68,17 +72,20 @@ Variables --------- Never, under any circumstances, should implicit variables be used! Always -include ``implicit none`` in Fortran source code and define all your variables. +include ``implicit none`` and define all your variables. -32-bit reals (``real(4)`` and ``float``) should never be used. Always use 64-bit -reals (``real(8)`` and ``double``). +32-bit reals (real(4)) should never be used. Always use 64-bit reals (real(8)). For arbitrary length character variables, use the pre-defined lengths ``MAX_LINE_LEN``, ``MAX_WORD_LEN``, and ``MAX_FILE_LEN`` if possible. +Do not use old-style character/array length (e.g. character*80, real*8). + Integer values being used to indicate a certain state should be defined as named constants (see the constants.F90 module for many examples). +Always use a double colon :: when declaring a variable. + Yes: .. code-block:: fortran @@ -102,6 +109,8 @@ Always put shared variables in modules. Access module variables through a ``use`` statement. Always use the ``only`` specifier on the ``use`` statement except for variables from the global, constants, and various header modules. +Never use ``equivalence`` statements, ``common`` blocks, or ``data`` statements. + Indentation ----------- @@ -154,30 +163,19 @@ each side. Do not leave trailing whitespace at the end of a line. ----------------- -Fortran-Specific ----------------- - -Conform to the Fortran 2008 standard. - -Use <, >, <=, >=, ==, and /= rather than .lt., .gt., .le., .ge., .eq., and .ne. - -Do not use old-style character/array length (e.g. character*80, real*8). - -Always use a double colon :: when declaring a variable. - -Never use ``equivalence`` statements, ``common`` blocks, or ``data`` statements. - ------------- -C++-Specific ------------- +--- +C++ +--- Miscellaneous ------------- +Follow the `C++ Core Guidelines`_ except when they conflict with another +guideline listed here. + Conform to the C++11 standard. -Always use C++-style comments (``//``) as opposed to C-style (``/**/``). (It +Always use C++-style comments (``//``) as opposed to C-style (``/**/``). (It is more difficult to comment out a large section of code that uses C-style comments.) @@ -197,23 +195,42 @@ Do not use using-directives e.g. ``using namespace foobar;`` Do not use C-style casting. Always use the C++-style casts ``static_cast``, ``const_cast``, or ``reinterpret_cast``. +Naming +------ + +In general, write your code in lower-case. Having code in all caps does not +enhance code readability or otherwise. + +Struct and class names should be CamelCase, e.g. ``HexLattice``. + +Functions (including member fuctions) should be lower-case with underscores, +e.g. ``get_indices``. + +Local variables, global variables, and struct/class attributes should be +lower-case with underscores (e.g. ``n_cells``) except for physics symbols that +are written differently by convention (e.g. ``E`` for energy). + +Const variables should be in upper-case with underscores, e.g. ``SQRT_PI``. + Curly braces ------------ -For a function definition, the opening brace should be on the same line as the -end of the function definition. The closing brace should be on its own line. -If the entire function fits on one line, then the closing brace can be on the -same line. e.g.: +For a function definition, the opening and closing braces should each be on +their own lines. This helps distinguish function code from the arugment list. +If the entire function fits on one line, then the braces can be on the same +line. e.g.: .. code-block:: C++ - return_type function(type1 arg1, type2 arg2) { + return_type function(type1 arg1, type2 arg2) + { content(); } return_type function_with_many_args(type1 arg1, type2 arg2, type3 arg3, - type4 arg4) { + type4 arg4) + { content(); } @@ -272,6 +289,7 @@ Use of third-party Python packages should be limited to numpy_, scipy_, and h5py_. Use of other third-party packages must be implemented as optional dependencies rather than required dependencies. +.. _C++ Core Guidelines: http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines .. _PEP8: https://www.python.org/dev/peps/pep-0008/ .. _numpydoc: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt .. _numpy: http://www.numpy.org/ From 37671e1792327e7c8f6f58f0f26503f99abc960e Mon Sep 17 00:00:00 2001 From: Sterling Harper Date: Wed, 13 Dec 2017 18:10:17 -0500 Subject: [PATCH 3/4] Fix styleguide typos --- docs/source/devguide/styleguide.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/source/devguide/styleguide.rst b/docs/source/devguide/styleguide.rst index 4bba8f4c01..a0500965eb 100644 --- a/docs/source/devguide/styleguide.rst +++ b/docs/source/devguide/styleguide.rst @@ -18,7 +18,7 @@ Miscellaneous Conform to the Fortran 2008 standard. Make sure code can be compiled with most common compilers, especially gfortran -and the Intel Fortran compiler. This supercedes the previous rule --- if a +and the Intel Fortran compiler. This supersedes the previous rule --- if a Fortran 2003/2008 feature is not implemented in a common compiler, do not use it. @@ -171,7 +171,8 @@ Miscellaneous ------------- Follow the `C++ Core Guidelines`_ except when they conflict with another -guideline listed here. +guideline listed here. For convenience, many important guidelines from that +list are repeated here. Conform to the C++11 standard. @@ -203,7 +204,7 @@ enhance code readability or otherwise. Struct and class names should be CamelCase, e.g. ``HexLattice``. -Functions (including member fuctions) should be lower-case with underscores, +Functions (including member functions) should be lower-case with underscores, e.g. ``get_indices``. Local variables, global variables, and struct/class attributes should be @@ -216,7 +217,7 @@ Curly braces ------------ For a function definition, the opening and closing braces should each be on -their own lines. This helps distinguish function code from the arugment list. +their own lines. This helps distinguish function code from the argument list. If the entire function fits on one line, then the braces can be on the same line. e.g.: From b666d9b49ef21004f81e74dea66ff85022dfe4e0 Mon Sep 17 00:00:00 2001 From: Sterling Harper Date: Mon, 18 Dec 2017 00:23:57 -0500 Subject: [PATCH 4/4] Improve references to Core Guidelines in style doc --- docs/source/devguide/styleguide.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/source/devguide/styleguide.rst b/docs/source/devguide/styleguide.rst index a0500965eb..89d5673943 100644 --- a/docs/source/devguide/styleguide.rst +++ b/docs/source/devguide/styleguide.rst @@ -174,13 +174,16 @@ Follow the `C++ Core Guidelines`_ except when they conflict with another guideline listed here. For convenience, many important guidelines from that list are repeated here. -Conform to the C++11 standard. +Conform to the C++11 standard. Note that this is a significant difference +between our style and the C++ Core Guidelines. Many suggestions in those +Guidelines require C++14. Always use C++-style comments (``//``) as opposed to C-style (``/**/``). (It is more difficult to comment out a large section of code that uses C-style comments.) -Header files should always use include guards with the following style: +Header files should always use include guards with the following style (See +`SF.8 `_: .. code-block:: C++ @@ -191,10 +194,8 @@ Header files should always use include guards with the following style: ... #endif // MODULE_NAME_H -Do not use using-directives e.g. ``using namespace foobar;`` - Do not use C-style casting. Always use the C++-style casts ``static_cast``, -``const_cast``, or ``reinterpret_cast``. +``const_cast``, or ``reinterpret_cast``. (See `ES.49 `_) Naming ------