Writing Code that Lasts

Adapted from Writing Code that Lasts Longer by Steve Merritt published Dec 28, 2019

In order of what I think is most important.

Modularize

• The more lines of code that a developer must keep in their head at one time, the harder it is to reason about. Split your system up into its logical components and install interfaces between them. This simple step, which often gets discarded as over-engineering, ensures that the various parts of the system can be worked on separately, and therefore your development velocity will be higher.

• In addition to different functions, within a function you can make sections with comments.

  // Initialization ----------------------------

  <section 1 code that initialized variables>

  // Find Optimal Value -----------------------

 <section 2 code that finds some optibal value>

  // Delete Temporary Variables --------------------

  <section 3 code that deletes variables>

  // -----------------

Simplicity (Maintainability) > Optimization

• Try to keep things as simple, strightforward, and obvious.
  • For implementation, try to keep things simple enough to give a presentation that people can understand.
  • If you’re naming a variable, NAME THE VARIABLE BY ITS NAME PLEASE (or give me a comment, but I prefer it named something obvious). If a variable represents a package name, don’t name it pkgn. Name it packageName.

• The cost of a subsystem is measured not just in system resource usage, but also in the cost of developer time associated with that subsystem. If you optimize your code with tricky, clever shortcuts but as a result no one can understand how it works, you have saved a few thousand dollars in resources but incurred tens of thousands of dollars in developer cost when your successors are forced to slowly comprehend your work, or alternatively, rewrite the system. Not to mention the cost of your time optimizing it.

• If you encapsulate correctly and have proper profiling metrics, down the road you can identify problematic latencies and drag-and-drop optimized component implementations without affecting the greater system. Therefore there’s no opportunity cost to start with the simpler version.

Show Your Work

• Comment explanations & links to websites that you referenced that will assist others in understanding what's occurring. This will help others understand the project so they won’t be overwhelmed and speed up how long it takes to onboard someone onto the project.
  • View Documentation section for more information

Clear, explicit test code

• Depending on projects, testing TAKES SO MUCH TIMEEEEEEEEEEEEE. So, make it as easy to update the tests as you can. Try to plan for “What if people change this” scenarios. Planning for what could be implemented in the future and how that will affect testing facilitates testing saves a lot of time.

• If someone is going to change your code, they will probably break your tests. This is all well and good, because they have changed the behavior of the system. However, if you haven’t written your tests clearly enough, it will slow down the developer as they will struggle to determine what the intended behavior of the test originally was, which must be understood in order to correctly modify the test to account for their change.

Journal

• 2020.05.15 Created Writing-Code-That-Lasts.md
• 2020.07.03 Updated syntax
• 2020.07.14 Added order of importance and more explanation
• 2020.07.19 Updated titles
• 2021-04-09 Added link to Documentation page