Clarify style guidelines in the online documentation and set up `clang-format`

[superwhiskers]

related to #54 / #82, albeit it deserves a dedicated pull request to unbundle it from the addition of pre-commit

rationale

currently, CONTRIBUTING.md is insufficiently precise in some ways and the repository's existing .clang-format file is not used and does not match the conventions within CONTRIBUTING.md exactly. clarifying the style guidelines and setting up .clang-format would help maintain a consistent style across the codebase and potentially make it more welcoming to newcomers

considerations

• how is existing code formatted in relation to what is documented in CONTRIBUTING.md?
• how should the codified style be imposed upon existing code?
  • should we incrementally reformat code when it is touched, or should we reformat it all in one go?
• should we add a precommit hook?
  • this would necessitate reformatting it all in one go, unless some work was done to detect modified files within the hook
  • or should we use pre-commit instead, as described in Add pre-commit configuration + GitHub Actions #54?
• what additional linting tools should we use and how/when should they be applied?

initial suggestions

• drop Add pre-commit configuration + GitHub Actions #54 & Precommit addition to the repo #82 for now
• open a new pull request deleting the existing .clang-format file in .github/workflows¹ since it isn't used and remove the dead code within the root CMakeLists.txt² that references it
• create a new .clang-format at the repository's root which takes into account existing style conventions + the stuff within CONTRIBUTING.md, with a priority toward the latter, updating CONTRIBUTING.md accordingly
• do not apply the styling to existing code until a solution is agreed upon

Footnotes

1. https://github.com/ORNL/ReSolve/blob/develop/.github/workflows/.clang-format ↩

2. https://github.com/ORNL/ReSolve/blob/d913854aed438af040f6ecd5bee052da3a861baa/CMakeLists.txt#L56-L58 ↩

[superwhiskers]

some additional comments:

• we should consider setting up clang-tidy to provide naming convention enforcement
• as was done in Precommit addition to the repo #82, integrating cmake-format would be a good idea

[pelesh]

@cameronrutherford and @ryandanehy, please chime in.

CC: @kswirydo

[cameronrutherford]

Closed #82. I think we could close #54 without doing C++ formatting, and then have the clang-format and clang-tidy hooks added in another PR/Issue.

+1 to the clang-tidy suggestion. Might be worth discussion in another issue and closing out one thing at a time.

[pelesh]

• open a new pull request deleting the existing .clang-format file in .github/workflows1 since it isn't used and remove the dead code within the root CMakeLists.txt2 that references it
• create a new .clang-format at the repository's root which takes into account existing style conventions + the stuff within CONTRIBUTING.md, with a priority toward the latter, updating CONTRIBUTING.md accordingly

I think @superwhiskers makes a good point. We can use #151 to test locally the .clang_format file and update instructions in CONTRIBUTING.md as needed. I suggest we mere #151 once we agree upon code style standards for Re::Solve. Then we reopen #82 and set pre-commit hooks and perhaps other actions as needed.