Episode 488: Chris Riccomini and Dmitriy Ryaboy on the Missing Readme

Walkthroughs

Walkthroughs during code reviews are essential for understanding complex changes. Dmitriy Ryaboy and Chris Riccomini emphasize the importance of providing rich context to reviewers, especially when dealing with intricate systems like a company's financial ledger 1. Chris explains that even small changes in such systems require detailed walkthroughs to ensure the entire team comprehends the modifications and their implications 1. Dmitriy adds that asynchronous reviews often fall short for large or complex changes, advocating for in-person or virtual walkthroughs to facilitate better understanding 2.

Sometimes the change is big enough that a little blurb isn't sufficient to really get people to understand it.

--- Dmitriy Ryaboy

Felienne Hermans notes that while asynchronous comments are useful, real-time discussions can trigger insights that might not emerge in isolation 1.

   

Communication

Effective communication strategies are crucial during code reviews, particularly when discussions become contentious. Dmitriy highlights the importance of face-to-face conversations to resolve misunderstandings that can arise from text-based exchanges 3. He suggests preemptive discussions when changes are sophisticated or involve multiple stages, ensuring everyone is aligned on the project's direction 3. Chris shares his experience with open-source projects, where in-person chats, though not common, can significantly enhance collaboration and community engagement 3.

It's easy to lose tone and to not understand where people are coming from when you're just exchanging text messages.

--- Dmitriy Ryaboy

He encourages developers to initiate these conversations, as they often lead to more engagement and understanding than expected 3.