Here at Herrmann International one of our key fundamentals is that we try to "eat our own cooking" and use Whole Brain® Thinking in our own work. This post is part of a series where some of our team members talk about some ways they use Whole Brain® Thinking for their day-do-day work.
This post is by our Lead Software Engineer, Andrew Swerlick.
At first glance, software development might not seem like a job that involves a lot of day-to-day Whole Brain® Thinking. After all, a lot of what our team does seems like it's firmly situated in the technical, analytical A quadrant. Sure, we do have to collaborate with other internal teams on product design, requirements gathering, etc., but when it get to the point where our developers put their fingers to the keyboard and start writing code, all the other quadrants go away, right?
When I first started at Herrmann a couple of years ago, I probably would have said yes. But recently, our development team has adopted some practices that are showing me the value of writing Whole Brain® code.
These changes came out of an evaluation of our code review process. For those who aren't familiar with the concept, code review is a practice that most development teams adopt to help ensure high quality software. It's pretty much exactly what it sounds like: It's a process by which you ensure any code written by a developer is reviewed by at least a one of their peers. The reviewer(s) look over the code for obvious bugs, stylistic issues, clarity and new concepts.
After one of our last development cycles, we had identified some issues with the thoroughness of our review process and decided we wanted to write up some more formal guidelines for reviewers. We thought it might be interesting to try and structure these guidelines in the form of a Whole Brain® Walk-around. We weren't sure if it would really work, but it seemed like an interesting place to start.
At first, I was a little worried that this Walk-Around would be heavily weighted towards the A quadrant, but as I started working on it, I was pleasantly surprised to find that there was a lot of value in reviewing the code in a whole-brained fashion. After a few drafts and some discussion, this is what we came up with.
A disclaimer: Some of the items in the Walk-Around may be a bit technical for those who aren’t developers, but even so, you’ll quickly see how the process itself clarified for us that a Whole Brain® approach can help us think through all the issues and ensure we’re not overlooking anything important.
Focus on what the code is doing and how that aligns with the acceptance criteria, both explicit and implicit (i.e., performance, security, deployability)
- What is this code trying to do (according to acceptance criteria)?
- What is this code actually doing?
- Does this code access the database? Does it do so performantly? How do I know?
- Is data saved transactionally? Will any write operations result in invalid partial saves?
- Is this code covered by tests? Do those tests cover key edge cases? Do those tests line up with how the code will actually be called at runtime?
- Are these changes going to impact other existing areas of the application? Do I know those impacts have been sufficiently tested (either via automated or manual testing)?
- What will happen when this code starts operating on production data? Am I sure the testing that's been done locally sufficiently represents what's in production?
- What will happen when this code is running in parallel with older code during a blue-green deployment?
- What steps are involved in deploying this code, and are those handled via automation, or are they documented somewhere if they have to be manual?
Focus on how the code is written. Does it confirm to our various standards (stylistic, security, etc.)? Is it consistent with the rest of the code in the application?
- Does this code include inputs from a client (browser, etc.)? Are those inputs being validated from both a correctness and a security perspective?
- Does the code follow safe security practices (i.e., are database queries parameterized or only built from safe inputs)?
- Does this code follow good stylistic conventions? (See style guide documentation for individual applications and general style guide.)
- Does this code follow the same architecture principles as the rest of the code base? If not, why?
- Does the code use new tools or libraries, and if so, what necessitates that usage?
Focus on who this code is for. That means both the end users who will perform actions that touch the code and the other developers who will have to read and maintain it.
- Which end users will perform actions that touch this code? Does the code take that into account from a security and usability perspective?
- Does what's happening in the code clearly map to what end users are actually doing? Could you summarize the application behavior to an end user and they would “get it”? If not, why the mismatch?
- Is this code properly commented to explain the “why”?
- Is this code readable and clear to other developers?
- Is it clear what other parts of the application will be impacted by changes to this code? If someone touches it while you’re on vacation, will it be easy for them to make sure nothing else breaks?
Focus on how this code maps to the big picture of the business as a whole. Explore alternative approaches or models, both for the architecture and for individual lines of code.
- How do the concepts and ideas modeled in this code map to the the actual business goals and ideas? When they differ, is there a compelling reason?
- As requirements change based on our high-level goals, what changes might have to be made to this code? Will they be easy?
- Does this code use any third party tools and libraries? What are the implications of using that particular library or tool?
- Are there any alternative ways that a particular piece of code could accomplish the goals involved? Why use this particular way?
We've been using this Walk-Around for about a month now, and here’s what we’ve observed:
- In general, having a specific, comprehensive list of questions like the above has been great for reviewing our own code, too, even before it goes to someone else as part of a review. It's also sparked a lot more conversation in the pull request.
- The C quadrant focus on how other developers will read our code is definitely making us more conscientious about code clarity and commenting. It's prompting more discussions in pull requests and creating more shared understanding about our code base.
- Using the A quadrant to document and explore implicit requirements around performance, deployment steps and production behavior has helped our production deployments go more smoothly. It’s also helped us catch issues that weren't necessarily going to show up in our development environment.
It's definitely been valuable enough that we plan to keep using and refining it. To me, it's a great example of how Whole Brain® Walk-Arounds are incredibly useful tools that can be easily applied to all kinds of tasks, even those in very specific domains.
We've got lots of resources to make your team more innovative, efficient, productive and happy. Whether it's the software engineering team or some other group entirely, get your copy of the meetings toolkit to make more out of teamwork.