Justification for decisions made in the style guide

[GTcreyon]

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." 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." 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." 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

[AThousandShips]

I don't know that the style guide needs any justifications generally, it's just suggestions based on experience, everyone is free to use what suits them and this is just a suggestion

I don't think the presence or lack of a reason changes things, if it doesn't feel right for a user then it doesn't, no matter of reasoning will change their preferred style or feel

However, for the casese you mention:

• The two lines is because GDScript is an indentation based language and it is easier to navigate with multiple lines, it also clarifies the distinction between inside and between methods, as one inside, two outside, I think that explains itself, that the intention is to make it clear from a glance if something is in a method or not
• The plain text operators are probably because many users of GDScript come to GDScript without experience in other programming languages, and foo() and bar() is more intuitive than foo() && bar(), it also makes a clear distinction between the boolean and bitwise operators, like so foo() && bar() vs foo() & bar(), that is much harder at a glance

Code style is one of those things that have sparked countless flame wars in computer circles, and is very personal, so I don't think people will come to this page and decide based on the justifications provided, they will pick what feels right to them or what is most commonly used so they can just copy code, in either case I don't think many will go "well I would have followed this style if someone explained it to me, but I guess I won't now"

Just your own example shows that you are inclined to use !x over not x because of how you interpret it and how your brain reads that, and that's great! It's the nature of humans to be different. And if something doesn't make sense to you you shouldn't use it, if it doesn't matter in other ways, so I don't see how arguing in favor of the styles would matter much

But agreed some of the cases could do with further reasoning, but I think it's mostly a minor detail and that it doesn't really impact people's choice

[GTcreyon]

it's just suggestions based on experience, everyone is free to use what suits them and this is just a suggestion

Indeed, it's just a suggestion. If the style guide were a mandatory list of commandments, they would not need justification, since I'd be forced to use it and the question of "why" would be irrelevant. But if I'm being given a choice, I would like to understand my options, no?

I don't think the presence or lack of a reason changes things, if it doesn't feel right for a user then it doesn't, no matter of reasoning will change their preferred style or feel

Indeed. It's not a matter of convincing a user why their way of doing things is "wrong," because such a thing does not exist.

But the style guide exists for a reason, no? If I'm going to decide to adhere to it, it would be useful to know the thought process behind it, so that I can evaluate it. If it's unsubstantiated, then it might as well be arbitrary, and the only benefit at that point is consistency with other projects.

That's not necessarily bad, since consistently is valuable in its own right. But it clearly isn't arbitrary, since the statements made up above indicate that there is at least some kind of intent behind it. It just feels like a waste to have that intent muddied because it's not elaborated upon.

However, for the casese you mention:

The explanations you provided are excellent! And they give me reason to feel comfortable matching the style guide over my own personal preference. I write code not for myself, but rather for whoever might need to read it, so understanding the style guide helps a lot with that. Adding these explanations (or a peer-reviewed version of them) to the style guide would address my issue in its entirety, and add clarity to the conventions provided. That can only be a positive, no?

Code style is one of those things that have sparked countless flame wars in computer circles, and is very personal

For many people, it isn't so personal. It's a democratic issue to decide upon a consensus for. For people who find it a personal issue, they will not be interested in the justifications, and that is okay. This proposal isn't intended for them.

I'm suggesting this as benefit to people like me and my colleagues, who would like to make a decision as a team as to what our style guide will be. Doing so is much easier when we can understand and appreciate the intent behind the official one.

Just your own example shows that you are inclined to use !x over not x because of how you interpret it and how your brain reads that, and that's great!

It is great! And I appreciate that. But I'm not the only one who reads my code - it's an open source project. My team reads it, the community reads it, people who I will never meet will probably read it. I want it to be written in a way that is best for everyone who reads it.

The style guide claims that using not is "most accessible". That's a very attractive phrase, and it sounds like it's based in some kind of research, even if anecdotal. If so, it would probably trump my personal preference. But I can't make that decision, because such research - if it exists - isn't made clear to me as a user. So, I'm left in limbo where I can't decide whether it's an arbitrary decision that I should overrule, or an intentioned one that I should trust.

if something doesn't make sense to you you shouldn't use it

Exactly. In this case, the reasoning behind the "something" isn't provided, so I can't evaluate whether it makes sense to me or not.

In this comment chain, you explained it to me eloquently, and I can therefore decide that it does make sense to me, and I will use it. It would be nice to put that in the style guide document where everyone can read it, even if they conclude that they disagree.

I think it's mostly a minor detail

That's fine, it doesn't need to be major.