Hello and welcome to the second edition of Pragmatic Shorts! For more context check the introduction to short #1, A pragmatic philosophy.

I highly encourage you to read David Thomas and Andrew Hunt’s great book, The Pragmatic Programmer. This book is an awesome compilation of years of knowledge and experience from the hands of experts in software engineering.

Pragmatic Shorts, are cheat-sheet like space with a point like summary of the parts of this book that I’ve considered most relevant in my day to day job as a Software Development Engineer.

A Pragmatic Approach (Part 1)

A pragmatic approach of actions you can take while writing code that your future self and other developers will thank you at some point. You may want to see this a proactive efficient approach in opposition to a well known Damage’s Analysis after neglecting some of this concepts in a hard to maintain software.

I’ve decided to separate chapter parts in order to emphasize certain concepts and to keep this shorts short.

Have you ever worked in a not-small piece of software and bumped into what seems like a single, quick change to adapt to a changing requirement, or a small bug fix, that should be trivial to make, but turns into a great nightmare where many things break? or an endless chain of errors involving multiple modules? These are the kind of situations that can be avoided with a careful design and mechanism to keep the lights on.

So let’s begin:

• Good design is easier to change than bad design – Everything is when designed when it adapts to the people who use it, ETC(easier to change) principle
• ETC is a value, not a rule, is meant to be a guide residing among your conscious thought subtly taking you towards the right direction
• Frequently spend some time asking yourself “Did I made the overall system easier or harder to change?”
  • Implicit premise: You could tell which paths will be easier to change (some sort of educated guess)
  • If you don’t have a clue is OK. Try to make what you wrote as a replaceable piece of code
• (This is one of my favs) DRY (Don’t repeat yourself) – Every piece of knowledge should have a single, unambiguous, authoritative representation within a system.

• Knowledge changes constantly and fast and programmers are often in maintenance mode, where it’s easy to duplicate, hence, future updates turn into a maintenance nightmare by updating all the sources of knowledge
• DRY is intended to avoid duplication of knowledge and intent
  • Across internal APIs → Get tools to specify your API, document, and, ideally, have a central repository
  • Across external APIs → Import the API spec into your local APIs. If you can’t find a formal documentation consider creating one on the APIs you use
  • Data sources → Introspect your data schema, remove duplication, generate containers. Also rather than writing code that represents external data in a fixed structure, stick it into a key/value data structure and add a validation layer to verify that your map contains the least amount of information you need in the format you need
  • Inter-developer → The hardest, build a strong team communication, encourage it to be frequent and active (stand ups, forums, or any non-intrusive mechanism), also you may appoint a project librarian with enough context to be a source of knowledge for other members.
• Uniform Access principle: All services offered by a module should be available through a uniform notation which do not betray whether they are implemented through storage or computation
• Make it easy to reuse – If it isn’t easy, people won’t reuse it
• Orthogonality: decouple as much as possible, two things are orthogonal when changes in one don’t affect the the other. This is closely related to DRY principle and make systems easier to develop, understand, test, debug and maintain
• Non-orthogonal systems are more complex to change and control, for a high interdependence there is no such think as a local fix.
• Eliminate effects between unrelated things – You want to design components that are self-contained: independent and with a single, well-defined purpose, this will decrease development and testing time, promotes reuse, combines easier with other components
• These cooperating independent modules are useful to be set into layers of abstractions which reduces runaway dependencies
• A test for orthogonality: Map your components and ask this: “If I dramatically change the requirements behind a particular function, how many modules are affected”. It should be only one for an orthogonal system.
• Don’t rely on properties of things you can’t control.
• Be careful to preserve orthogonality if you introduce third party toolkits and libraries by asking yourself if this impose changes that shouldn’t be there (eg. create an special access to an object that removes encapsulation)
• Techniques to avoid duplication:
  • Keep you code decoupled → in a shy code modules don’t reveal anything unnecessary to other modules and don’t rely on other’s implementations (Law of Demeter)
  • Avoid global data → every reference to global data ties itself to that shared data
  • Avoid similar functions → Duplication means structural problem, check the Strategy Design pattern
• Orthogonal design is easier to test, every unit is easier to specify. Unit testing itself is an orthogonality test as well
• Orthogonality applies to documentation as well