Unique subchapters per rule and consistent order

[PhilippSalvisberg]

Most of the guidelines have just two examples chapters. Good and bad. That's ok.

Some guidelines have multiple good/bad chapters (adding all examples under one chapter with comments might be the better option):

• G-3195 (one example set: bad, good, good - no good variant is better than the other, but looks strange)
• G-3120 (two example sets: bad, better, good, bad, good)
• G-4220 (two example set: bad, good, bad good)

Some guidelines use the pattern "Bad - Better - Good":

• G-2410
• G-3120 (two example sets)
• G-4120
• G-4310
• G-4350
• G-7730
• G-7430

Some guidelines use the pattern "Bad - Good - Better" (meaning the last option is the best):

• G-3310

Personally I'd like to have a standardized subtitle concept. This would simplify the process of generating the SQL-Script examples for the CLI and the rules representation for PL/SQL Cop in general and SonarQube in particular (the genmodel). But this should not drive the solution. I can always deal with exceptions.

Two things are important IMO:

• Unique subchapters per guideline (different names are OK, multiple examples per chapter are also OK)
• Consistent use "Better". Maybe using "Best" instead of "Better" would make things clearer.

[PhilippSalvisberg]

I changed the example file guideline_3310_na.sql which is part of the PL/SQL Cop CLI to "Bad - Better - Good". This way it is consistent with the other rules.

"better" in this context is more meant as an improvement, a step in the direction of good. This works in German. But does it in English? I think yes. But I'm not sure. It's different to good - better - best.

[kibeha]

Had a twitter discussion about "bad - better - good" versus "good - better - best".

https://twitter.com/kibeha/status/1313740507328253954?s=20

Lots of opinions, but I think most ended up reasonably agreeing that "better" is relative and is to be understood as "better than the previous value in the sequence", meaning both versions are valid English.

https://twitter.com/MDWidlake/status/1313788475016122368?s=20

But by that definition, "better" needs a sorted order to make sense.
In "bad - better - good", better is > bad but better is < good.
In "bad - good - better", better is > good.

I do not see it as a big issue, but yes, there ought to be a consistent usage of the terms.

On the other hand, complete consistency makes it hard to "grade" examples.
Like for example if I have two "good" examples (but one better than the other), I might choose "bad - good - better" (where better is understood as "even better".)
But if I have a not-as-bad-as-bad-but-still-not-quite-good-example, I might choose "bad - better - good" (where better then is understood as better than nothing but not really good.)

Ideally we'd want un-ambiguous words to describe levels of "good" for the examples.

• bad
• better (ambiguous, but maybe okay in context)
• good
• best

Guideline with 2 examples - use bad and good.
Guideline with 3 examples can use "bad better good", "bad good best", "bad good good" - depending on "goodness level" of each example.
Guideline with 4 examples could be "bad better good best" or combos like "bad good good best", "bad better better good", etc.

Alternatively drop the word and grade the examples by smileys

• :-(
• :-|
• :-)
• :-D

[PhilippSalvisberg]

I agree with "bad - better - good - best".

For examples with multiple "bad" and "good" examples I would squeeze all good examples in one chapter and all bad examples in one chapter. If necessary some comments can be added.

Here are two screenshots of the representations of G-3195 and G-4220 in SonarQube:

And here's the representation of G-5030 which contains comments in the code (also for the error part to ensure the code is valid).

[kibeha]

Example subchapters are now consistently 4 levels:

• Example (bad)
• Example (better)
• Example (good)
• Example (best)

Most rules have bad+good, some have bad+better+good, few have bad+good+best.
So far none have bad+better+good+best, but that would be allowed.

Cases where multiple examples exist of the same "goodness level", they have been combined into a single subchapter, so there are no rules with multiple identically named subchapters.