quantum icon indicating copy to clipboard operation
quantum copied to clipboard

Add missing linter/formatter config files

Open mhucka opened this issue 2 months ago • 2 comments

This adds a couple of files for tools used by scripts in ./scripts/:

  • A config file for YAPF, copied from the TensorFlow repo. Even though it's very simple, it's useful enough because it prevents people getting incorrect results if they decide to run yapf directly. (The default used in this project and TensorFlow is Google style, but that's not the YAPF default.)

  • A config file for clang-format. This is based on the one from the TensorFlow repo and adds a section for Protobufs, because clang-format can format protobuf files too.

mhucka avatar Jan 12 '26 22:01 mhucka

We already have formatting scripts for both cpp and python, I don't know if we need these.

MichaelBroughton avatar Jan 12 '26 23:01 MichaelBroughton

We already have formatting scripts for both cpp and python, I don't know if we need these.

Adding configuration files for linters and formatters is useful even if a project has shell scripts to run the tools. It's a common, widely-accepted best practice in open-source projects. Here are some reasons I can come up with, and there are probably more:

  • Many editors and development environments have extensions that automatically detect and use standard linter/formatter programs. This lets the editor/IDE provide devs with real-time feedback. It can only do that correctly if the tools can determine a project's standard settings for those tools. Those are lost if configurations are embedded as command-line arguments within shell scripts and not made explicit.

  • Related to the previous point: txternal tools, such as pre-commit hook frameworks (like pre-commit, which I use), and also some GitHub Actions action steps, often integrate more seamlessly with standard configuration files rather than custom scripts. For example, they may have an option to tell them where to find the config file for a particular linter or formatter – but not necessarily an option to run a script that invokes the tool.

  • When configurations are done using command-line flags in scripts, if a change needs to be made for a linter or formatter configuration, we have to find and modify all the instances where that linter or formatter is called. The more complex the scripts, the easier it is to miss a case or make a mistake. Config files centralize the tool configurations.

  • Config files make the project's coding style rules explicit, version-controlled, more transparent, and easier for anyone or anything (e.g., GenAI coding tools) to find and understand. It makes it easier to onboard new contributors and help them learn a project's setup: when a contributor wants to know "What coding style does this project use?", they are more likely to think of looking for a config file because it's more common.

  • Config files make it easier for devs to get the right settings when they want to run the linters and formatters in ways that are not anticipated by the authors of the shell scripts.

mhucka avatar Jan 15 '26 21:01 mhucka