Skip to content

Instantly share code, notes, and snippets.

@pankkor

pankkor/on_writing_code.md

Last active October 20, 2025 09:19
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save pankkor/94a8c6f956419720ded3455287ff9936 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save pankkor/94a8c6f956419720ded3455287ff9936 to your computer and use it in GitHub Desktop.
Download ZIP
Brain dump on writing code
Raw
on_writing_code.md

“There are no solutions. There are only trade-offs.” ― Thomas Sowel

TL;DR:

  • Writing code is craft. Master your craft.
  • Keep it simple.
  • Writing simple code is hard.
  • Simple code is rarely celebrated as an achievement. Folks worship meta-programming when old school macro can do the trick.
  • Code is liability. Prefer removing code over adding it. Strongly prefer removing code in big codebases.
  • Complexity kills. Kills UX, development times, quality, costs, debugability, comprehensibility.
  • Every time complexity is introduced to the system it multiplies the costs.
  • Complexity is compounding. Complexity on the base layer of the system is amplified by following layers and becomes serious problem. You didn't have time to pay attention to compile times? Development productivity plummeted, you need more build farms, smarter caches, sophisticated build tools and more build engineers to manage all that.
  • Keep features to minimum. Engineer small but generic subset features with emergent behaviors rather than combinatoric explosion of micro-features that don't naturally interact and break on edge cases.
  • Develop and test your code under sanitizers. Fuzzy test all user input.
  • Code reviews are mostly useless. Small problems shall be caught by sanitizers, tests and dev manual testing. And it's usually too late to fix any big problem that is exposed on code review.
  • Prefer architectural pre-reviews over code post-reviews. Ask smart colleagues to review your design, make a draft PR early on that lays out all the architecture.
  • Don't discuss code style on code review. Outsource those boring parts to clang-format, your linter or just ignore. If the code is coherent nothing else is important.
  • Don't discuss C++ on code review. Code solves business problem and brings value to the customer, discuss that instead. Discuss requirements, interface boundaries, control flow, state management, performance.
  • Know how your target hardware works. Having a simplified mental model of how modern hardware works is usually enough to get huge gains in performance. 
  • Having a basic understanding of hardware capabilities will allow you to see parts of system that could be 100x more performant and pick better designs for your systems.
  • Forget about OOP. Forget about SOLID, OOD no one is doing it right. Forget about Clean Code™. These are subjective metrics and taste preferences.
  • Prefer big self containing modules with clear cut APIs. Users of your module shall work with it as with a black box. If it has reasonable API it's internals don't matter. If API is good all the internals could be quickly rewritten without effecting the users. If API is bad then all external users of the code now are coupled to your bad API and have to be rewritten.
  • I will rephrase: If module API was designed to be performant someone can come in and optimize the internals. If your API doesn't allow performant solution, than your whole module and all USER code has to be rewritten. Apply this to the whole project and now you see why projects suffers from complete rewrites over and over again.
  • Learn old ways of programming. Instead of designing API to give away shared_ptr objects and worrying about lifetimes, give away a 64bit generational handler. When handler is invalid your system shall return NULL data.
  • "Performance" doesn't mean hand written assembly. "Performance" means being aware of your target platform and perform reasonable data transformations.

On API It's hard to design proper API top down (especially if it's a novel problem to solve). Prefer discovering API from performant (not necessary fully optimized) low-level implementation.

  • There are some common principles in good APIs:
  • API is a boundary in between the modules. API creates a barrier to make certain code transformations. Where to put this barrier depends on a lot of circumstances (number of people in the team, their experience, data patterns etc) and is specific to the project. That's why it's not a good idea to reuse someone's else's architecture.
  • Good API is a boundary set propertly. It allows to change internals witout affecting the USERS.
  • Good API is tightly coupled to the way you keep and process your data. Abstract API that doesn't take that into consideration is cancer to the project. It forces it's users to have bad API and implementation as well.
  • Good API is centered around data, not functions. Data as input, data as output and a "business logic" is data transformation in between.
  • Good API takes into account hardware requirements: bandwidth, target hardware and metrics. Don't have hardware requiremens? It's time to decide on a min spec.
  • Suggestions how to test API ergonomics: write your API first with empty implementations. Write usage examples. Tweak API. Repeat. Ask fellow colleagues to use your API. And only when API is stable start implementation (no, it's not the same as TDD).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment