Code Style

Readability

• Does using newer language features make code less readable?
  • Question inspired by a Slack thread at work in which a colleague expressed the opinion that…
    • The JS/TS ?. operator is confusing and an example of how using niche language features makes code harder to read for people just learning the language
    • The way to make code more readable is to choose patterns that exist across multiple languages
  • Lots of interesting discussion followed:
  • Are the latest language features “jargon”?
  • Should advanced usage of a language be considered “jargon” if some team members are not yet familiar with it?
  • Should a team stick to older language patterns for easier onboarding or language hoppers?
  • Is terse syntax jargon?
  • What level of language familiarity should “jargon” measured against?
• Folder structure:
  • Colocate files that change together (e.g. a component and its tests)
  • Organize by feature, not by type?
• Code comments:
  • Identify what problem what kind of code comments solve
  • examples of projects with long comments
  • do new coders benefit from comments?
    • can enough context be presented without commenting on the why?
  • commenting on the why (not the what)
  • Don’t Write Comments • A surprisingly convincing case that code comments are problematic and better replaced with code that reads just as clearly • Code Aesthetic 📺
• Is it easier to read functions that take a single (object) argument?
  • “watch out for a functions that take multiple arguments. It’s hard to remember what each argument does and easy to get the order wrong. often in this situation taking an object leads to a much cleaner API” • Jack Franklin 💬
• Variable names:
  • “Coming up with good variable names can be a challenge. For boolean values, you can follow this convention. Prefix it with is, has, or can… • Samantha Ming 💬
  • JavaScript naming conventions: do’s and don’ts • Brandon “Woz” Wozniewicz 📖
  • Naming things needn’t be hard - Classnames • Paul Robert Lloyd 📖
• Reduce nesting of conditional logic:
  • Code: Align the happy path to the left edge • Mat Ryer 📖
  • Why You Shouldn’t Nest Your Code • How to use extraction and inversion to reduce nesting and align the happy path to the left • Code Aesthetic 📺
  • Inversion of Conditional Blocks • A good example of how to flatten nested conditional statements to make logic easier to understand at a glance
  • Cleaner IF statements // Clean Code • I’m a big fan of this pattern of guard clauses with early returns rather than nesting conditional
• Code is run more than read • “It is basically always the case that the long-term costs of keeping a system working reliably vastly exceed any inconveniences you encounter while building it.” • Facundo Olano 📖

Links

• Clever Code Considered Harmful • “As engineers, it can be really satisfying for us to implement clever, terse solutions to problems, relying on advanced tricks and techniques. As a result, we often write code that is hostile and inaccessible to the junior folks on our team. This article makes the case that we should strive to write simple, accessible code, using the dumb old primitives that everyone knows.” • Josh Comeau 📖

Bikeshedding

• Tabs vs spaces:
  • Tabs are objectively better than spaces | Go Make Things • Today, I wanted to talk about how tabs are objectively better than spaces. This won’t take long.
  • Tabs vs Spaces - CSS Weekly • Should you use tabs or spaces? It might seem irrelevant which option you chose, but tabs are actually more accessible and, therefore, a better option.

Abstraction vs Coupling

• Abstraction Can Make Your Code Worse • The cost of abstraction is more coupling, so be careful about automatically abstracting all repeated patterns • Code Aesthetic 📺

Inbox

• Encapsulation • “Typically, functions are written for their reusability, but I want to convince you that the reason to reach for a function is to encapsulate a concern” • Kyle Shevlin 📖

• No, really: YAGNI - by Thorsten Ball - Register Spill • Don’t add that code that might be useful later • Thorsten Ball 📖