We aim to integrate and expand our coding standards documentation into our GitHub repo as restructured text files under the docs/dev directory. This documentation will include internal style standards, guidelines on updating standards, and best practices for coding, logging, and when documentation should be written. The aim is to facilitate internal discussion and eventually share these standards externally. A pull request for the layout and skeleton of the coding standards documentation has been submitted (PR #467), but further additions are necessary. It is our aim that this documentation help support new contributors. It is also our aim that almost all of these standards are enforced automatically, rather than by us in PRs.
Background and Motivation
Establishing coding standards is crucial for maintaining consistency across the project, simplifying the management of pull requests, and avoiding repetitive discussions on standards. We have created a draft coding standards reference document in Google Docs and are now transitioning this to our GitHub repo. This move is intended to centralize the discussion on coding standards, facilitate communication between CIRA, NRL and others and lay out a comprehensive plan to ensure clarity and avoid derailment in developing and maintaining these standards.
Alternative Solutions
Do not develop standards
Environment
Documentation will reside in the docs/dev directory, which is not currently live and not built with Sphinx. Standards aim to cover Python coding practices, including the use of Black and Flake 8 linters/formatters, NumPy docstring standards, PEP-8, and IDE configurations, etc, etc.
Code to demonstrate issue
N/A - This issue pertains to project documentation and standards rather than code.
Checklist for Completion
[x] #487
[ ] #486
[ ] Define standards for documentation requirements
[x] #488
[ ] #501
[x] #502
[ ] Define conventions for default IDE settings for consistency.
[ ] Update pull request templates and issue workflows to reflect the new coding standards.
[ ] Finalize the internal style standards, including guidelines on code touching and updates.
biosafetylvl5
commented
2 months ago
Writing coding standards
Description
docs/devdirectory. This documentation will include internal style standards, guidelines on updating standards, and best practices for coding, logging, and when documentation should be written. The aim is to facilitate internal discussion and eventually share these standards externally. A pull request for the layout and skeleton of the coding standards documentation has been submitted (PR #467), but further additions are necessary. It is our aim that this documentation help support new contributors. It is also our aim that almost all of these standards are enforced automatically, rather than by us in PRs.Background and Motivation
Alternative Solutions
Environment
docs/devdirectory, which is not currently live and not built with Sphinx. Standards aim to cover Python coding practices, including the use of Black and Flake 8 linters/formatters, NumPy docstring standards, PEP-8, and IDE configurations, etc, etc.Code to demonstrate issue
Checklist for Completion