Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add C++ code Formatting #420

Open
wants to merge 7 commits into
base: main
Choose a base branch
from

Conversation

mabruzzo
Copy link
Contributor

@mabruzzo mabruzzo commented Jul 18, 2024

Pull request summary

This PR adds a support for using clang-format with Enzo-E.
I have added extensive documentation.

Detailed Description

This is something we spoken at length about in the past and there is consensus enforcing standard formatting for C/C++ code would be beneficial.

I feel like this is something we could delay indefinitely. So I made 2 particular choices to make this easier to merge:

  1. To avoid merge-conflict I have excluded just about all existing files from clang-format.
    • If we don't do this we will be trapped in a cycle of waiting for PRs to be closed (which never ends)
    • I think there's value in applying formatting new files and "ripping the band-aid off" later for the older files
  2. I decided to "just make a decision" about code-formatting.
    • This is something that we could endlessly bikeshed, and I think it would be beneficial to choose now.
    • I basically choose the Google C++ style and made a few very minor adjustments based on a few different choices made in the LLVM style (the two styles are extremely similar). I have put forth a similar style in Grackle.
  • I have reformatted a small subset of existing files to show what the style looks like. I'm happy to make changes if you see something egregious.
  • For the most part, I think we should leave iteration on minor details to a later date. That's the beauty of code-formatting.

Relationship with pre-commit

The main challenge of using clang-format is that it is not forward/backward compatible (picking an established style should mitigate some of these issues). - In other words, you need to apply a consistent version of clang-format everywhere.

  • Since clang-format is part of the LLVM project, this can be somewhat non-trivial to enforce (it could be very inconvenient to start requiring people to use).
  • If we didn't take any steps to address this problem, it could be a large inconvenience.

SOLUTION: To address this challenge, this PR configures the pre-commit software and pre-commit.ci continuous integration service (introduced in #419) to invoke clang-format.

  • Essentially, you will be able to modify the formatting of proposed changes in a PR without locally installing any software by leaving a comment that says "pre-commit.ci autofix" to a PR (then a commit will be added to your branch to fix the problem).
  • To easily run clang-format locally, I recommend installing the pre-commit software on your machine and invoking that software. The pre-commit software will download its own personal copy of clang-format to use for formatting (it won't affect the rest of your system)
  • I have added extensive documentation about how this works (and how to do it).

I implemented a similar solution in Cholla and it works well.

This is a major change or addition (that needs 2 reviewers): unknown

Depends on #419

PR Checklist

  • New features are documented with narrative docs.

@mabruzzo
Copy link
Contributor Author

At the last Enzo-E call, it was suggested that I try to format everything and check if it works.

  • A branch of the repository where everything is formatted can be found here.
  • I confirmed that everything definitely compiles when we do that

@jobordner jobordner self-assigned this Oct 17, 2024
@mabruzzo
Copy link
Contributor Author

mabruzzo commented Nov 21, 2024

pre-commit.ci run

EDIT: For posterity, this comment was used to trigger the new pre-commit.ci continutous integration (this was necessary since I introduced precommit.ci after this PR was created and I didn't want to push a new commit)

@mabruzzo
Copy link
Contributor Author

pre-commit.ci autofix

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants