workflows icon indicating copy to clipboard operation
workflows copied to clipboard

Style Guide rules under review

Open a-frantz opened this issue 6 months ago • 0 comments

  1. All quotes that can be double quotes should be (only use single quotes where necessary, such as when nesting quotes)
    • I don't like this phrasing, but I'm not laboring over the words ATM
  2. All comma delimited lists/arrays/objects/etc. should have a trailing comma
    • again, not a fan of my phrasing here. Should be workshopped before entering the guide
    • I can easily find the link if requested, but from memory black has a very good rationale for their stance on trailing commas and I say we follow that example.
      • The summary of that rationale is that it makes adding/reordering/removing items from a list less error prone. They might have additional arguments, but the above is enough to convince me.
  3. All lists/arrays/objects/etc. should have one element per line (i.e. newline separate items). A key/value pair are considered one element.
    • Is this controversial? It goes further than black which says short lists with few items should be collapsed to one line.
    • I think this is justified by the fact it's easier to read and edit/rearrange IMO. Does anyone disagree?
    • In #115 I complain our files have too many lines. This exacerbates that issue (but I think we already do this? I don't think officially adopting this rule would actually require changes to our code)
    • Benefit: This rule is trivial to enforce with code. The alternative would be having some line width cut-off or other logic to calculate before deciding to collapse/split lines. Easier to implement via code is better IMO.

The common thread on these 3 rules is that they are all trivial to enforce via an auto-formatter tool (and tedious/annoying to enforce manually). Therefore, I vote we hold off adopting these officially till that auto-formatter has reached fruition. Mainly to keep our codebase compliant with our documents.

a-frantz avatar Dec 14 '23 17:12 a-frantz