Skip to content

Commit

Permalink
Extract Project-level recommendations from General Coding Style and add
Browse files Browse the repository at this point in the history
the entry about one-off scripts

We don't want one-off stray scripts to lay around. They litter
the project space. In rare cases when a script could be useful again,
it could be retrieved from the history.
  • Loading branch information
evgenyz committed Jul 2, 2022
1 parent ff2541c commit b3619c0
Showing 1 changed file with 12 additions and 8 deletions.
20 changes: 12 additions & 8 deletions docs/manual/developer/04_style_guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,20 +46,24 @@ In practice, this implies:
Extract functionality to separate functions or convert functions into classes with multiple methods to avoid this.
* If a function contains try/except block, there should be no other logic present apart from exception handling.
* Name variables and functions properly, don't hesitate to use longer identifiers.
Use explanatory variables to help the code to express itself -
Use explanatory variables to help the code to express itself --
assign a result of the operation into a variable that describes its meaning even if you intend to use it only once.
* Don't copy-paste code, use e.g. jinja macros to reduce duplication.
Exception to this rule is code that is identical another piece of code only by coincidence, and there is a substantial probability that the code can diverge.
* Include tests for your contribution.
* Write comments if and only if there is no chance for the code to explain itself.
* Don't put authorship information into the code, Git tracks authorship for you.
Don't copy-paste license text into source files -- use [SPDX IDs](https://spdx.dev/ids/) for that purpose.
* Don't take part in making files longer - files longer than 400 lines should be an exception.
Add your new code into a new file, and possibly move existing code to it in the same or in a follow-up PR.

When working with existing code that doesn't satisfy these recommendations, simply leave the code in a better shape than the shape in which it was before,
and keep these guidelines in mind when writing new code.

## Project-level Coding Style
* Include tests for your contribution.
* Don't take part in making files longer -- files longer than 400 lines should be an exception.
Add your new code into a new file, and possibly move existing code to it in the same or in a follow-up PR.
* Don't copy-paste code, use e.g. Jinja macros to reduce duplication.
Exception to this rule is code that is identical another piece of code only by coincidence, and there is a substantial probability that the code can diverge.
* Don't put authorship information into the code, Git tracks authorship for you.
Don't copy-paste license text into source files -- use [SPDX IDs](https://spdx.dev/ids/) for that purpose.
* Don't commit one-off scripts to the project.
On occasions when one would like to get a feedback on the approach or debug the script,
that makes automated changes to the project in a PR, it is strongly recommended to add a removal commit before merging the PR.

## Text-level Coding Style

Expand Down

0 comments on commit b3619c0

Please sign in to comment.