godotengine / godotengine/godot-docs
Justification for decisions made in the style guide
- Dominant language
- reStructuredText
- Stars
- 5.7k
- Forks
- 3.8k
- Avg merge
- 1d 20h
- Merged PRs (30d)
- 25
Description
**Your Godot version:**
4.2
**Issue description:**
Decisions made in the style guide are often based in some judgement on what is most useful to the reader/author of the code. For example: ["This results in easier refactoring and better diffs in version control as the last line doesn't need to be modified when adding new elements."](https://docs.godotengine.org/en/4.2/tutorials/scripting/gdscript/gdscript_styleguide.html#trailing-comma) These help convey the intent behind certain conventions. It clearly states what the convention solves, and how. It helps make informed decisions on when it is reasonable to deviate from the style guide, while also demonstrating the value of writing in line with it.
However, many decisions are not substantiated with accompanying justifications. For example: ["Surround functions and class definitions with two blank lines."](https://docs.godotengine.org/en/4.2/tutorials/scripting/gdscript/gdscript_styleguide.html#blank-lines) Why surround functions and class definitions with blank lines? Why two, rather than one or three?
Other times, justification is given, but not substantiated with evidence. For example: ["Prefer the plain English versions of boolean operators, as they are the most accessible."](https://docs.godotengine.org/en/4.2/tutorials/scripting/gdscript/gdscript_styleguide.html#boolean-operators) Most "accessible" how? To whom? People who are less experienced with programming? People with sight or reading difficulties? What makes "not x" more accessible than "!x"? Was there a survey or study conducted on how readers might see each option?
Such detail is excessive, but a little extra explanation would help. I personally find "!x" to be easier to interpret than "not x", because the lack of space between the operator and the operand helps me interpret it as a unary operator without having to write it as "(not x)". Now, that *might* be sufficient reason to begin using "!x" project-wide. But, the style guide seems to have *some* reason for preferring "not x". But when all that's stated is that it's "most accessible", it's unclear whether my evaluation is more significant than the standard.
In short, I think it would help if the reasoning behind style guide decisions was made clearer to the reader, by providing concrete reasons and then justifying those reasons.
**URL to the documentation page (if already existing):**
Stable, 4.2 as of writing: https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/gdscript_styleguide.html
4.2, static: https://docs.godotengine.org/en/4.2/tutorials/scripting/gdscript/gdscript_styleguide.html
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.