Frontend coding guidelines at my company

gistfile1.md

Some Common Sense

• Murphy's rule: whatever can go wrong, will go wrong
  • Expect the unexpected
• Be liberal in what you accept, and conservative in what you give out
  • Never trust client data
    • Validate it
  • Allow clients to send whatever
  • Things shouldn't crash
    • Fail gracefully

TypeScript

At this org, we use TypeScript. It's almost a superset of JavaSript, and if we disallow non-erasable syntax (such as the private keyword in function parameters), then TypeScript is a proper superset of JavaScript.

In section about "Some Common Sense", we have a point that reads "never trust client data: validate it". How do we do it? At this org, we use Zod. Although, we do welcome anything else, but it's at this point becoming a quasi industry standard, but we don't discourage the use of anything else.

Coding Style

• Avoid default exports, unless a parent framework expects it
  • Reasons
    • Default exports can be accidentally renamed
    • Default exports could have us accidentally load in the same module more than once
    • Default exports are hard to refactor
• Avoid the use of any; it's a legacy feature for teams needing to migrate their code away from JavaScript onto TypeScript. If you need a top type, you should use unknown
• Use erasableSyntaxOnly for TypeScript projects; have things as close to JavaScript as possible
• Avoid any draft features of the ECMA262 standard
• Always format code in accordance to the Prettier configs (even if Prettier isn't literally used, at least adhere to the standards of Prettier)
  • Use prettier so that:
    • We avoid debating the minutia
    • We have a standard when parsing code
• Complex CSS classes are a red flag
• Composition over inheritance
  • This is more an aphorism in the world of React before the transition away from class components over to functional components and hooks
• Use generics whenever you can

Some Unconventional Unlearnings

• Flat file structures are fine. Organizing things into hierarchies is overrated; do it if you really feel it helps you
• Don't bother with descriptive names; actions speak louder than variable names. What it does is more valuable than what it's claiming to value
• Reusable code is overrated; don't even bother
  • Avoid Hasty Abstractions (AHA)
  • Write Everything Twice (WET)
    • Just a heads up: this rule as worded is nonsense. But you have got to understand the context for why this is even relevant: it was created to fight overzealous efforts to minimize code duplication, when code duplication is perfectly fine. The overzealous effort to avoid writing duplicate code exists to avoid lazy reuse of code, that really could have been abstracted away
      • A good example where code duplication is fine is instead opting for idioms as opposed to function names.
        • If we're OK with using function names over and over again, then we should be fine using the same pattern of code over and over again. This is called idiomatic programming
          • Some people argue that idiomatic programming exists to let the compiler optimize a common code path, but nevertheless, the sentiment around idiomatic programming predates smart compiler optimizations
• Domain specificity in code is a red flag
• It's better to write testable code than to write tests
  • Write tests, but before that, write testable code; then write tests

Philosophy

• do things that don't scale
  • we're working on a software as a service. It's a service, and like any service, we cater to individual customer needs, and not get hung up on uniformity
    • that said, we should be cognizant of identifying things that do scale. A technique to use is called "compression-oriented programming", or "semantic compression"
• a programmer who strives to make their code as undeletable as possible is most likely to have their code deleted

Some Readings

Semantic Compression
Casey Muratori
Date Published: May 28, 2014.
Date Accessed: June 19, 2025.
URL: https://caseymuratori.com/blog_0015

Casey Muratori critiques the widespread misuse of object-oriented programming (OOP), illustrating how developers often prioritize abstraction and reusability prematurely, leading to convoluted codebases. Using a UI panel from The Witness as a real-world example, he advocates for a "compression-oriented" approach: write code for specific cases first, then generalize only when duplication appears. He emphasizes semantic compression — reducing cognitive and structural redundancy in code — as the most efficient way to develop maintainable systems. Muratori's process involves recognizing patterns, extracting reusable logic organically, and building minimal yet expressive structures, rather than following heavyweight OOP design methodologies. The article is both a programming philosophy and a practical case study in bottom-up design.