When making architectural decisions, you will always have to analyze solutions and weigh trade-offs. You must make decisions that best serve the architectural characteristics you wish to support.
One of the best ways to evaluate architectural decisions is to use a pros and cons whiteboard, brainstorming with your team on the pros and cons of a particular decision. Always balancing trade-offs is the first law of software architecture.
What’s the second law of software architecture? “Why is more important than how”. For future engineers, we need to record why certain decisions were made. This is important to have decisions to point back to as we continue to develop the software throughout its lifecycle.
Architectural decision records
Architectural decision records (ADRs) are important to record why we made a particular decision and overtime they’ll build into an architecture decision log. An ADR has seven (7) sections:
- Title - consists of a three-digit numerical prefix followed by a colon, and a concise title about the decision
- Status - consists of three (3) states, Request for Comment (RFC), Proposed, and Accepted. If something changes, an ADR can supersede an existing one. This should be documented in both ADRs.
- Context - a summary of the requirements, situation, or need for the ADR
- Decision - the decision made
- Consequences - identification of what systems or people this change affects
- Governance - how do we plan to enforce this decision now and into the future?
- Notes - metadata about the ADR, such as:
- Original author
- Approval date
- Approved by
- Superseded date
- Lat modified date
- Modified by
- Last modification