liveBook · Manning

Architectural problem

As explained in "Looks Good to Me"

A defect in the high-level structure or design approach of an application.

An architectural problem occurs when the high-level approach taken in a change is incorrect. It is difficult to resolve during code review because the team must choose between rework that delays delivery and accepting technical debt. section 4.4.4

Reduce the chance of architectural problems reaching review by:

  • Discussing new features thoroughly before implementation. section 4.4.4
  • Defining clear acceptance criteria for each feature. section 4.4.4
  • Making questions and requests for help safe during development, especially for junior, new, or less talkative teammates. section 4.4.4

A difficult pull request

A pull request reaches review with an incorrect high-level design. The team must decide whether to request rework and delay the timeline or accept the implementation and introduce technical debt. Earlier feature discussion and clearer acceptance criteria could have exposed the problem sooner. section 4.4.4

How "Looks Good to Me" covers it

How deep it goes
Defines the defect and its review tradeoff, but does not detail architectural analysis techniques.
Examples
Uses a pull request with an incorrect high-level approach and a choice between rework and technical debt.
What you can do after
Diagnose architectural problems earlier by discussing features, clarifying acceptance criteria, and inviting questions.
How it connects
Connects architectural problems with code review, technical debt, acceptance criteria, feature discussion, and psychological safety.
Cover of "Looks Good to Me"
liveBookmanning.com
Read "Looks Good to Me" on liveBook Get the book at manning.com

Related concepts

This explainer was generated by Manning's knowledge graph from the text of "Looks Good to Me". The section links point to the parts of the book it draws on.