Skip to main content

Source Code Principles

Author: Alexander Galamaga | Created Apr 21, 2025

Purpose​

The purpose of this doc is to provide aspirational guiding principles around contributing source code to the codetrikcs.org repositories.

Principles​

  1. Source code mitigates ambiguity of words: “Ambiguity of words is the greatest impediment to advancement of human knowledge”. Computer code has an advantage over plain English because it can be interpreted by machines unambiguously. Strive for lack of ambiguity not just for machines but also for humans reading the code.

  2. Optimize for understanding over brevity. Add comments setting the context wherever implicitly derived (e.g. when using annotations, explain what they do and how they work, add links to documentation in code)

  3. Express TLDRs as code. Express high-level business logic as functions of various levels of abstraction (10k feet, 20k feet, 30k feet, 40k feet zoom in / zoom out), that communicate the work breakdown structure at varying resolution, where one can drill down to lookup implementation in greater detail. When making a business logic assertion, strive for code that fits in under one screen, delegating details to classes/methods.

  4. Compounding effect. Focus on writing code that expresses durable business logic that has an intrinsic value proposition of its own. Segregate boilerplate code implementing transient framework adapters from the core business logic of the product. The latter should have a compounding effect, where prior building blocks serve as tools accelerating future development exponentially. Don’t retire code too soon. Even if not currently used, save a method to a gallery of known building blocks that can be consulted for reference in the future.

  5. Divide and conquer. Split class files that are over 300-500 lines of code. Think of classes as human agents that specialize in one thing. Organize “org-charts” of classes in meaningful package hierarchies, following high cohesion loose coupling principle. Periodically review and rebalance the package hierarchy.

  6. Don’t repeat yourself. Periodically review code for duplicates or similar methods & classes, and consolidate where reasonable. Do not deduplicate algorithmically different implementations of the same method, even if one is deemed superior to another: keep options open for “supplier diversity”. Use abstraction classes (Factory pattern) to support supplier diversity.

  7. Proudly-found-elsewhere over not-invented-here. When a third-party library substantially increases implementation velocity, doesn’t constrain development flexibility, and doesn’t add a lot of boilerplate code, don’t be shy to adopt.

  8. Express assertions as code. When making an assertion (e.g. stating a hypothesis, reporting a defect), express it as a unit test, a SQL query or a bash script.

  9. Avoid the temptation of fixing a bug before you have a failing test. Make it easy to compare the before and after states to make sure you’re fixing the right thing.

  10. Build a thermometer before you build the oven. Have your success measurement tool expressed as code (e.g. SQL query) to unambiguously define KPI.