Style can mean a lot. It may provide a sense of structure, can act as a mark of quality, enable understanding for new user, or even aid in recognition of a project. In may ways, style is the beating heart of the FinOps++ streaming from the desire to produce exactly these outcomes.
To help with this, when designing the structure of the Assessments project, we looked closely at how to provide a style scaffolding via time-tested specifications and popular linters.
It is strongly recommended to use pylint for linting for python code. While yamllint is recommended for the YAML components specifications. And pymarkdownlnt (also called pymarkdown for short) can be used to spot check the Markdown documentation.
There are built-in configuration files for these in the top-level directory of this project that will help make sure your code is compliant with the project's standards. These packages can be pretty easily installed in CLI Tool with the following modification to the pip install command python -m pip install -e ".[validation]".
Caution
There is an older and unaffiliated (and unmaintained) package called pymarkdown. For security reasons, make sure to not download this version by installing specifically pymarkdownlnt if you choose to install the dependencies separately into your environment.
One other Linter that we run against your code on pull-requests is cspell. This is actually a Node.js based CLI tool that provides a basic means to spell check the project. As configured in .cspell.config.yaml, this is used as a glorified typo finder. So, between this and the fact that CSpell doesn't use Python, we won't require users to download an run this. But any failures found during the analysis of the pull request will need to be fixed.
Tip
For those that do want to go above and beyond, feel free to follow along with the CSpell Installation instructions from cspell to get the tool up-and-running.
This project makes use of the YAML specification v1.2.2 for all files with the .yaml extension. That largely includes the action, capability, domain, and profile component specifications that are used generate other core pieces of FinOps++ such as the Markdown components.
Differences from the standard specification used for FinOps++ can be found in the yamllint configuration file .yamllint. The biggest change being that FinOps++ makes uses of 2 spaces for indentation rather than 4. This was chosen on purpose to help readability when it comes to nesting used by the component specifications.
Largely, this project work around the GitHub Flavored Markdown, but should generally also work well with the CommonMark. Files that are governed by these specifications largely have the .md extension, there there are some exceptions such as the files found under guidelines/ or the project's base README.md.
Even when these specifications are enforce, there are some difference related to handling of HTML elements when creating nested tables for the framework markdowns. Additionally, we also along line-lengths of 120 characters rather than the typical length of 80. But generally we try to keep as close as possible to these specifications. These (hopefully) minimal changes can be found in the pymarkdownlnt configuration file .pymarkdown.
All python modules and code with the .py extension generally hold to the PEP 8 standard. Deviations generally are around things like line-length, where much like the Markdown change, we allow 120 character lines. We also use PascalCase for local variables rather than the standard UPPER_CASE format.
The full list of changes (honestly, the full list of configuration even including basic defaults) can be found in .pylintrc. This might be a bit hard to read, and if you are really interested in seeing the differences, would suggest running pylint --generate-rcfile > .pylintrc2 in another directory and compare the differences using a tool like diff in *nix like environments or something like Compare-Object in PowerShell.