TL;DR — There are several benefits to you, your team, and your project by doing an end-to-end review of a “slice” of an application in which you have no prior experience.
Context
Our team at work has been assigned to work on a component of an application that hasn’t seen significant feature development in several years. To add a few more wrinkles, the developers (and architect) for that component are no longer with the company, and this was one of the first components developed (i.e., we’ve learned some things since then and haven’t had time to retrofit this particular component).
It was a daunting feeling for me to lead sprint planning — where others are looking to me for expertise in breaking down the work and setting the course for the ship, so to speak — when I honestly had no idea how anything worked under the hood. During my tenure on this project, so far the vibe around this component was “here be dragons,” so I knew I had my work cut out for me.
The first task I assigned myself was to walk through the application (UI to database and back) and document how two common workflows are executed.
How I did it
There are plenty of ways to describe how your system works — swim lanes, class diagrams, screen recordings of you walking through code, etc. I chose something fairly low-tech: PowerPoint to combine basic boxes and arrows along with a sequence of slides showing the state of the call stack as the workflow executes. By showing the call stack one slide at a time, you can also annotate what’s going on — what values are passed to a method, what properties are on various types, etc. I like this approach because you don’t need much to get started — PowerPoint, Visual Studio, tool for screen captures — and you likely have them in your dev environment anyway.
(I’d love to share the PowerPoint presentations I developed, but the nature of my project precludes me from doing so. Given the system is fairly complex, mocking up an example of equivalent scale would take a fair amount of effort and would likely be overkill in this case.)
Photo credit: Danny Clark
Thought processes while building the review
I kept in mind the reasons I was putting this slide deck together in the first place:
- Understand the moving pieces and how they interact so that I can extend functionality of the component
- Help others on my team understand so they knew where the work would “live”
- Build documentation for posterity, or for lessons learned
With that, I got a better sense for my audience — who I would be presenting this to the following week, and who would be looking at this review months from now.
The process of stepping through the code line by line helped me affirm what I already understood about the application and also challenge some assumptions about how I thought things were working (some of which turned out to be incorrect).
I ended up asking myself a variety of questions, imagining myself having to explain this to either a junior developer or someone completely new to this project. For example…
- Where does that WPF control live?
- How does that button know what to do when I click it?
- Why is this class in that particular assembly?
- How does this view model get the data to pass to the service when the data is on some other view model?
- Is this code we implemented in-house, or is Entity Framework handling something for us?
- Why does this method take an IQueryable and this other method take a List? Why does that matter?
- There’s some interesting validation logic — when does that get connected?
- How does this entity line up with this database view?
- What’s a database view, and where would I find that in SQL Management Studio?
- We get some pieces of information through ADO.NET calls to stored procedures in one place, and LINQ to Entity Framework in others. What’s going on there?
Benefits
For starters, there’s the adage of “if you want to understand something, teach it to someone else.” Throughout the learning process, I was playing Devil’s advocate — what questions would other developers ask me, and did I have answers ready for them?
Reviewing older sections of code is almost like reading a history lesson. I was trying to understand what those developers were thinking, what direction they were heading, and what tools/design patterns they had at their disposal. I also discovered some pretty interesting ways of grouping things together and leveraging the syntax of the language. This plays into the concept of “if you want to get better at writing, do more reading.”
It didn’t feel intuitive having my first sprint tasks involve writing zero lines of code. Having code that already works makes it tempting just to jump in and start tinkering. My philosophy in this case was “you have to slow down to speed up.” I wanted to understand what was there so I could make intentional choices about what I could reuse and what I needed to amend (or eliminate and replace with something better).
Not only was this an architecture review, it was a code review of sorts as well. I found several opportunities to make small adjustments to improve code quality and application efficiency.
Having to navigate each layer of the system deepened my understanding of what each layer is doing and why. This means I understand what the UI, the core logic, and how the database is being leveraged. It exposed some areas I was weaker on, and I emerged more informed than when I started.
These PowerPoint slide decks can be shared with other developers (or even checked into source control) to act as living documentation of workflows in our system. It saves future developers the time of figuring out how this component works, and in this format, is more “persistable” than debugging via a live demo.
Sharing this review with the team broke down silos of knowledge — not only about the component, but about the techniques used to build the component. We could affirm our current approach as a group, and also discuss opportunities for improvement.
Wrapping up
The few days I spent focusing on two common workflows for a new-to-me area of the application were quite informative. I feel more prepared to make informed decisions about how to implement the upcoming features, and my team is more knowledgeable because of my efforts. I would encourage other developers to try this technique if they find themselves in a similar situation.