How to write software

HowToSoftware.md

Axioms

• Why > How
• Reliable velocity, not quick wins.
• Agility - Change is the default
• Pragmatic - Driven by Why, not how, hype, or the crowd.
• Idiomatic - Leverage and prefer basic, composible, and reusableknowledge over proprietary/ecosystem knowledge.
• Derivability over memorization.

Documentation:

• Document, Why the code documents How
• Who is it for?
• Less documentation is better than More
• Simplifiying a process is exponentially more valuable than documenting a complex process.
  • Faster onboarding
  • Less maintainence
  • Better agility

Software

• Less software is better than More
• Write for readability:
  • Software is written for humans to understand, and THEN for computers to execute.
• YAGNI: https://martinfowler.com/bliki/Yagni.html
• Decouple early, Abstract late.
  • Pave goat tracks: https://en.wikipedia.org/wiki/Desire_path
• Single responsibility:
  • Components (modules / functions) should do one logical thing.
  • Components' names should clearly describe their responsibility.
• Style
  • Non-esoteric
  • Consistent per project/service/module (not globally)
• Testing
  • Test intent, not implementation.
  • Test at the boundaries (HTTP for servers. Dom for Web Apps. API for modules etc)
    • Avoid Mocks where possible
  • Aim for 100% coverage.
  • TDD where practical/pragmatic.
• Dependencies
  • Strive for fully reviewed codebases.
  • Well tested.
• Peer review gate to master.

Tools

• Reject by default, use only when value STRONGLY and CLEARLY outweighs the cost.
• Tool costs:
  • Maintenance
  • Readability
  • Learning curve/knoledge gap from no-tool
  • Build/run time (for bundlers, test tools, etc..)
  • Bundle size (for bundled/served code)
  • How hard is it to replace with a different tool?
• Single responsibility (more features is bad)