Company
Date Published
Author
Eli Perkins
Word count
829
Language
English
Hacker News points
None

Summary

Architecture decision records (ADRs) are an effective method for documenting the rationale behind decisions within a codebase, and have been increasingly adopted since 2017, particularly in long-lived codebases like those in enterprise settings. At GitHub, the mobile team uses ADRs to record decisions affecting iOS and Android codebases, enhancing long-term clarity and communication. ADRs are not just for immediate reflection but serve as a reference for future revisions, allowing developers to recall their mindset at the time of the decision. They facilitate better team understanding and communication by detailing the decision-making process, including alternatives considered and pros and cons, which helps in onboarding new team members and reduces the need for explanatory meetings. By writing ADRs, teams can achieve a collective responsibility for maintaining decisions, promoting decision socialization and improving the quality of pull request reviews. As teams grow, ADRs help manage the increasing complexity of communication lines and serve as a valuable tool for both current and future team members, ensuring a sustainable and well-documented code evolution.