ER: Adopting a coding style standard/guideline

[tony1ee]

Dependency

• Create a Roll Out Plan for adding Code Spell Checker VS Code Extension #4349

Emergent Requirement - Problem

As our project grow and attract contributions from a diverse group of developers, we have different styles of coding styles across our codebase (trailing spaces, spaces between operators, braces style, etc.). This poses a challenge for readability, maintainability and collaboration.

Proposing we explore the feasibility of adopting a unified coding format standard.

Issue you discovered this emergent requirement in

• Fix Our Events Card Glitch After Toggling and Resizing Window  #6777

Date discovered

05/01/2024

Did you have to do something temporarily

• YES
• NO

Who was involved

@tony1ee
@gaylem

What happens if this is not addressed

• Different styles of code pose a challenge for readability, maintainability and collaboration.
• The absence of guidelines for naming, formatting, and commenting practices could adversely affect our professionalism and compromise the quality of our work.

Resources

Why Prettier
Firefox CSS Guidelines
VS Code Formatter: TypeScript
Airbnb JavaScript Style Guide
Google JavaScript Style Guide

Recommended Action Items

• Make a new issue
• Discuss with team
• Let a Team Lead know

Potential solutions [draft]

We can solve this in several steps:

• Perform an analysis of existing codebase, including the language and file type.
• Research existing standardized guidelines and practices (potentially for each file type), then choose/define our standard
• Creating documents for reference and training
• Explore tooling and automation solutions: linters and formatters configurations in code editors, GHA checkers, etc.
• Consider either incremental refactoring or major refactoring for existing non-conforming code, depending on priority.

[roslynwythe]

• @tony1ee @gaylem thank you for presenting these ideas. Here at HfLA I am not familiar with a JS style guide such as the Airbnb or Google JS Style Guides, but I really liked the AIrbnb JS Style Guide and how it referenced the ESLint rules, so if a rule came up in VS Code, a dev could search the guide and find relevant advice.

@ExperimentsInHonesty are you interested in making use of a JS style guide in some manner?

[roslynwythe]

Regarding linters - I want to mention that there was some work done on ESLint and eslint:prettier

• DO NOT REVIEW: Prettier and research on setup via CL and Plugin #5023

• DO NOT REVIEW: GitHub Actions: Implement ESlint #5024

• Update wins.html file to use liquid in this file #5258

• Create a wiki page for linters used by the HfLA website team #3230

• Explore, document and make a new issue to implement linters which can be installed locally #2651

• Add ESlint VS Code installation instructions #4264

• You'll note that some of the above are still draft PRs. I believe there are several reasons why the work did not progress:

  • At that time we were still beginning the rollout of the spell checker and CodeQL and didn't want to roll out additional linters until those rollouts were complete
  • liquid./yaml code in JS files caused false positives with ESLint. Solutions discussed were:
    • moving liquid code to HTML - there are some samples of this in Update wins.html file to use liquid in this file #5258
    • ESLint recognizes comments such as // eslint-disable-next-line which ignores the rules for the next line of code, or // eslint-disable-line, which ignores the rules for the current line
  • For use on GitHub PRs, the GHA Super-linter was used. While Super-linter supports CSS and ESLint, it did not have a spell checker that was compatible with the Code Spell Checker for VS Code. So we might want to consider Mega-linter.

@ExperimentsInHonesty are you interested in restarting the discussion around ESLint and prettier?