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.

[shakedregev]

@pelesh Addressed here

[superwhiskers]

that appears to cover a portion of it but it lacks a clang-format configuration. additionally it creates a separate contributing guideline document in addition to CONTRIBUTING.md (without updating the latter). probably #242 should decide whether to merge the contents of its new contributing guideline document into CONTRIBUTING.md or to replace it, and if it were to completely cover the suggestions in this issue, should also contain a clang-format configuration implementing its prescriptions

[pelesh]

that appears to cover a portion of it but it lacks a clang-format configuration. additionally it creates a separate contributing guideline document in addition to CONTRIBUTING.md (without updating the latter). probably #242 should decide whether to merge the contents of its new contributing guideline document into CONTRIBUTING.md or to replace it, and if it were to completely cover the suggestions in this issue, should also contain a clang-format configuration implementing its prescriptions

Yes, I think it would be good to coordinate spelling out style guidelines and configuring clang-format. We are getting closer to merge #151.

I suggest we add pre-commit configuration with GitHub actions there, as suggested in #54.

I suggest we keep the file CONTRIBUTING.md with the link to the developer documentation and few other details.