A System for Analyzing Systems [Part 1]

We seek definition to understand the system so that we can discern
the rules so that we know what to do next so that we win.

— Michael Lopp, Being Geek: The Software Developer’s Career Handbook

How do you approach learning a new system that is dumped on your lap like a spilled plate of nachos? Let’s say somebody walks up to you and says:

Hey nerd- we need you to look at the EasyTrack system tomorrow – we have a buglist that we need you to churn through before the end of the week. Ralph was working on it but after his nervous breakdown he won’t return our calls.

As developers we are asked to jump into complex software systems all the time and a big part of our value is simply understanding systems (not just changing them or making new ones). This is a skill that we need to be intentional about. We need a system for learning systems. Here is mine.

First steps: Attitude

Avoid judgement of the people who have worked on the system, the client’s goals, the choice of typeface on the one page of system documentation, the developer’s skills and experience, the organization of the code, the choice of technology, the choice of coffee used during the project, the organization of the altar built to the stored procedure that does everything, et al.

You have no idea the in-the-womb conditions on the project and don’t know the real trade-offs that were in play. Like many negative emotions judgement will close you down and cloud your thought so keep a clear mind when reviewing a system. Starting with a good attitude will also help you in talking to people on the project later on.

First steps: Document

As you work through the steps document what you are finding. When I do this my goals are:

• To make me feel like I’m doing something as just staring at a new system can be brutal.
• To make a deliverable that I can publish at the end of the system analysis if needed.
• To allow me to have a place to store questions that I can’t find out from just reading code.

On that last point – I normally have Facts, Questions, and WTH sections in the document that I use as I work through a system. Facts are things that I have learned definitively about the system, Questions are open questions that I have researched and can’t find an answer to without asking someone or gaining access to something else, and WTH are bogeys – items that I see that I don’t understand that I’m deferring until later.

An example – as I’m reviewing the database I see an oddly-named stored procedure: spSyncOrderNoTransactionWithRollback? Hmm… So we add this to the WTH list until we can go back and read through it, where it is called, etc.  So we might end up with:

WTH

• In spSyncChangeOrderNoTransactionWithRollback – how can you have a rollback without a transaction – is this nested?

Which leads later to the following:
Facts

• Some of the stored procedures exist in the database but aren’t used by the application and are part of an export / sync process.  They start with spSync*
• Some, but not all, of the stored procedures use nested transactions with checkpoint.

Questions

• What is the export/sync process called by job execSync4_Bak that runs every night and calls the spSync* sprocs? [No access across linked server to the tables it is writing to]

As I work through the system I’m simply turning WTHs into Facts or Questions. The temptation once you have a basic understanding of the system is to stop typing – don’t do this.

If you maintain the facts list and polish it up you’ll have a nice system overview document. The easiest time to document a system is when it doesn’t feel like you are having to write-up up a bunch of things you already know.  So by writing while learning the system you can trick yourself into producing nice documentation that is much easier to keep updated later.

#1 Start with the data, don’t start anywhere else

I didn’t say start with the project plan, system documentation, email threads, interviews, test plans, or insulting notes about the system on the bathroom wall. The live data is the only thing that you can be sure is actually real in the beginning.

Show me your flowcharts and conceal your tables, and I shall continue to be mystified. Show me your tables, and I won’t usually need your flowcharts; they’ll be obvious.

— Fred Brooks, The Mythical Man-Month: Essays on Software Engineering

I’ve found this quote to be true – your code follows your data and you will get further faster if you understand the basic nouns in the application first. Seeing an Order table with a StatusId field gets you along the road faster than trying to read a 2,000 line method:

void placeOrder(int? productId, int priceStructureId, decimal price, int priceSigDigits, int userKey, string userNameInternational, bool isA, object? requiredBlob, out long intRetVal1, out long intRetVal3, out bool multi)

So go ahead:

• Create database diagrams to identify relationships
• Begin drinking if there are no enforced relationships
• Look at table sizes to identify transactional vs. configuration tables
• Look at meta and programmable database constructs – sprocs, functions, jobs, indexes, linked servers, etc.
• Begin thinking through the possible workflows – an Order table with OrderDetail which points to Product and PriceStructure implies that in the application someone is purchasing something and that prices vary.

#2 Use the application

If at all possible get a login to the application to view it as a customer does. You can’t always do this safely but you should try. Developers are always saying that the UI is the tip of the iceberg and that all the logic is in the back-end, but knowing the data model and having poked around the application will teach you the vocabulary of the system very quickly.

• What are the main uses cases [verbs] in the application?
• What nouns/entities that we saw in the data model are actually shown to the user?
• Is there data shown to the user that wasn’t in the data model? [hint for the next step]
• What doesn’t appear to be working or isn’t intuitive? Enjoy this perspective as once you learn the rest of the system you’ll lose it forever.

Tune in for the exciting – no electrifying – conclusion to how to analyze a system for fun and profit.