docs: Adding Code rules page #3915

MelReyCG · 2025-11-26T09:56:39Z

GEOS Code Rules

Aims at writing down the coding standards for GEOS, focusing on type safety, error handling, parallelism, and performance. Key principles include:

Type System
Memory Management
Error Handling
Parallelism
Performance
Memory / Safety
Architecture
Testing

These rules ensure code quality, consistency, and maintainability across the GEOS codebase.

arng40 · 2025-11-26T14:29:46Z

src/docs/sphinx/developerGuide/Contributing/CodeRules.rst

+      // BAD - Do not use std::vector
+      std::vector<real64> values;
+
+      // GOOD - Use GEOS arrays
+      array1d<real64> values;
+      arrayView1d<real64> valuesView = values.toView();
+      arrayView1d<real64 const> constView = values.toViewConst();
+


I don't understand with this code the benefits of GEOS array over std array

I added precisions to the comments

jafranc

Looks great ! Maybe there is the work of 2 docs there (or more 😄 )

jafranc · 2025-12-03T07:40:47Z

src/docs/sphinx/developerGuide/Contributing/CodeRules.rst

+Use GEOS tensor types for geometric and mechanical calculations:
+
+.. list-table:: GEOS Tensor Types
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Type
+     - Description
+   * - ``R1Tensor``
+     - 3D vector (real64)
+   * - ``R1Tensor32``
+     - 3D vector (real32)
+   * - ``R2SymTensor``
+     - Symmetric 6-component tensor (Voigt notation)


I feel like we can expand a bit on why tensor are in use and not their vector counter part

jafranc · 2025-12-03T07:41:52Z

src/docs/sphinx/developerGuide/Contributing/CodeRules.rst

+      map<string, real64> orderedMap;
+
+The following standard library components are allowed:
+- ``std::pair``, ``std::tuple`` for temporary structures, but beware of memory allocation, sometimes struct are to prefer.


Maybe an example on this specific point can help user

jafranc · 2025-12-03T07:42:49Z

src/docs/sphinx/developerGuide/Contributing/CodeRules.rst

+        setApplyDefaultValue( 1.0e-6 ).
+        setDescription( "Initial time step value. This parameter controls "
+                        "the starting time increment for the simulation. "
+                        "Valid range: (0, 1e-3]. See User Guide Chapter 5." );


For later, should we think of adding an optional setRange to Wrappers ?

I totally agree, along with "unit" type. This is the direction I want to promote.

jafranc · 2025-12-03T07:43:15Z

src/docs/sphinx/developerGuide/Contributing/CodeRules.rst

+- **Use GoogleTest framework**.
+- In GEOS, the goal of unit test is never to take position on the validity of physical results (this is the point of integrated-tests).
+- Place tests in ``src/coreComponents/<component>/tests/``.
+- Test GPU code paths if applicable (use ``#ifdef GEOS_USE_DEVICE``).


Would look nice in the example too

jafranc · 2025-12-03T07:45:08Z

src/docs/sphinx/developerGuide/Contributing/CodeRules.rst

+                             wrappedStats.stats().m_productionRate );
+
+      // statistics CSV output (only if enabled and from rank 0)
+      if( m_writeCSV > 0 && MpiWrapper::commRank() == 0 )


Why not wrap this in a MACRO and advise to use it ?

jafranc · 2025-12-03T08:07:41Z

src/docs/sphinx/developerGuide/Contributing/CodeRules.rst

+Additional Validation Guidelines
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Use ``setInputFlag()`` to mark parameters as ``REQUIRED`` or ``OPTIONAL``
+- Use ``setApplyDefaultValue()`` to provide sensible defaults
+- Use ``setRTTypeName()`` for runtime type validation (e.g., ``rtTypes::CustomTypes::positive``)
+- Document valid ranges in ``setDescription()``


Shouldn't it be in the Wrapper section ?

jafranc · 2025-12-03T08:17:11Z

src/docs/sphinx/developerGuide/Contributing/CodeRules.rst

+Caliper Integration
+^^^^^^^^^^^^^^^^^^^^
+
+Use ``GEOS_MARK_FUNCTION`` and ``Timer`` for performance tracking for the main computation functions / scopes.


and GEOS_CALIPER_MARK_SCOPE() then ?

jafranc · 2025-12-03T08:22:57Z

src/docs/sphinx/developerGuide/Contributing/CodeRules.rst

+Memory Management Rules
+---------------------------------
+
+Generalities
+^^^^^^^^^^^^^^^^^^^^
+
+- **Minimize dynamic memory allocation** as much as possible, particularly in performance-critical code,
+- For frequently allocated/deallocated objects, **consider memory pools**,
+- For containers with known size, **reserve capacity upfront**.
+
+Be Const / Constexpr
+^^^^^^^^^^^^^^^^^^^^
+
+**Use ``const`` and ``constexpr`` when possible**, enabling:
+
+- **Compiler optimization,** enables better code generation by giving constraints to the code,
+- **Code safety,** prevents accidental modification for constant contexts,
+- **Show code intention,** make code more readable.
+
+Also, **Mark methods const if the method is not designed to modify** the object state.
+


Same as above, it sounds like very high level advises, maybe better to relocate in another doc ?

I understand your feeling, and I think the same, strictly forbid useless mutability is a choice, thus a rule.
As it is a rule, it can give strict guidelines when reviewing code.
It is indeed a quite common one, but not enforced in all C++ applications.

I could put the reasons of rules in a foldable block to improve document readability.

I stay open to your feedback, do still you think that it should be moved?

I think the document could be two documents or main parts.

One high level C++ do/don't we choose and want to enforce (not sure it is doable).

One other that is more Domain Specific because GEOS's is using RAJA+CHAI and macros, and this is design/interface

What do you think of restructuring as follow:

Code Rules

Coding Practices

memory

perf

validation / precision

⁠architecture

GEOS Features

typing

documentation

testing

logging

error managment

parallelism

perf

physics-specific

I agree this'd be a good splitting 👍

jafranc · 2025-12-03T08:31:19Z

src/docs/sphinx/developerGuide/Contributing/CodeRules.rst

+Provide Views to Arrays
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+- When possible, prefer provide views to arrays (to const data if possible).
+- This **must** be done especially for RAJA kernels, and views must be **captured by value**.
+
+The rule is generalizable to ``string_view`` for strings, but not applicable in GPU context.
+
+Why Use Views?
+
+- **No memory allocation:** Views are lightweight references
+- **Mutability correctness:** Can provide ``const`` read-only access to inner data
+- **GPU compatibility:** Views work seamlessly on device
+
+.. dropdown:: Example: Views for arrays
+   :icon: code
+
+   .. code-block:: c++
+
+      // BAD - Creates a copy
+      array1d< real64 > copy = originalArray;
+
+      // GOOD - Creates a view (lightweight)
+      arrayView1d< real64 > view = originalArray.toView();
+
+      // GOOD - Const view for read-only access
+      arrayView1d< real64 const > constView = originalArray.toViewConst();
+


This might be moved above for more visibility ?

jafranc · 2025-12-03T08:59:18Z

src/docs/sphinx/developerGuide/Contributing/CodeRules.rst

+      arrayView1d< real64 > getView() { return m_data.toView(); }
+      arrayView1d< real64 const > getViewConst() const { return m_data.toViewConst(); }
+    };


detail but with class all will be private then ... struct ?

MelReyCG · 2025-12-03T15:45:13Z

Thanks @jafranc for your feedback, I'll take them into account.

MelReyCG added 2 commits November 26, 2025 09:32

📝 Code Rules page first draft version

c347dc0

📝 LLM test

eea776b

MelReyCG requested review from CusiniM, OmarDuran, castelletto1, dkachuma, herve-gross, jhuang2601, paveltomin and rrsettgast as code owners November 26, 2025 09:56

MelReyCG marked this pull request as draft November 26, 2025 10:03

MelReyCG requested review from arng40, jafranc and sframba November 26, 2025 10:03

arng40 reviewed Nov 26, 2025

View reviewed changes

MelReyCG added 2 commits November 26, 2025 16:35

📝 new draft version

25bf779

📝precised usage of container (Arnaud review)

d95a006

MelReyCG self-assigned this Nov 28, 2025

MelReyCG changed the title ~~Docs/rey/code rules~~ docs: Code rules Nov 28, 2025

MelReyCG changed the title ~~docs: Code rules~~ docs: Adding Code rules page Nov 28, 2025

MelReyCG added the flag: ready for review label Nov 28, 2025

MelReyCG marked this pull request as ready for review November 28, 2025 09:12

jafranc approved these changes Dec 3, 2025

View reviewed changes

docs: Adding Code rules page #3915

Are you sure you want to change the base?

docs: Adding Code rules page #3915

Uh oh!

Conversation

MelReyCG commented Nov 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

GEOS Code Rules

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jafranc left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MelReyCG commented Dec 3, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

MelReyCG commented Nov 26, 2025 •

edited

Loading