Monday, October 18, 2010

Software Archaeology for the Software Maintenance Developer

You are staring a new job and one of the first things you are expected to do is to understand the code base of the existing system and then to start fixing and adding code to it. What do you do?  There is no definite answer and will vary according to your situation.  But here are some tools and strategies which has helped me.

Even though these are partial to the Microsoft Development Stack, these techniques can be applied to other platforms as well.

Understanding the Source Code

  • Make sure you have the ability to search through the code and documents on your system.  If every thing is in a single solution, then your IDE like Visual Studio will be able to search through it.  Else I would recommend installing a desktop search tool.  I use Windows Search.  It does not matter what tool you use as long it can index your code, mark-up files and documents.  You need to be able to type in a keyword and in an instant get a listing of all the places in your code, comments and documents its being referred.
  • Scan through any available software design documentation.  But I would not trust it fully.  The documentations rarely keep pace with the code.  The code is the best documentation.  Although the design documents may help you understand the overall system architecture and conventions.

Understand your Layers

  • Know your Stack.  For example, 
    • What is your IOC library?
    • What JavaScript library is being used?
    • What tool is used for error logging?
    • What is the Unit Testing Framework?
  • If you are unfamiliar with any of the components in your stack, create a small testing application and play with it separately.  I find it difficult to understand unfamiliar libraries/tools from reading the production code as they are likely to be optimized for execution and encapsulated in other layers of libraries. Writing your own small sample projects will help you get a better understanding. When you find something in the code base you don't fully understand, you will already have a testing project to try it out.

Figuring out the Database

  • Setup your very own test database.  If its not possible, make sure you have access to a copy of the database you can play with without worrying about destroying the data.
  • In SQL Server Management Studio, "Database Diagrams" are very handy for getting a grasp on the layout of our database tables.
  • One neat trick is to create a new database diagram and add a table you are interested in.  Then right click on it and select "Add Related Tables".  This give you a nice overview of that module.
  • Red Gate make the best database tools.  And SQL Search, one of my favourite is free. It is a plug in to SQL Server Management Studio and is like Google for your database.
  • Did I mentioned Red Gate is awesome.  Another one of their cool tools is SQL Doc.  Although not free, try out the trial.  You can point it to your database and it will generate some nice html documentation with,  cross linked components. It gets even better,  If your dba was considerate enough to add some comments.
  • Start writing some Ad-hoc queries. And make sure they are saved in a place and format to allow for keyword searching later.

Make a Beginning

  • This may sound obvious, But I will put it in words anyway. Setup Debugging.  You need to be able to debug the code.  For those of you working with web applications,  you need be able to step through your client side scripts as well.
  • Start fixing some bugs. You are never going to fully read through and understand a standard sized commercial system fully in one go.  It's only going to happen over time.  Starting to fix issues will give you a sense of purpose and achievement.

And finally,

  • Unless you are in a unfortunate situation where there is nobody to talk to who knows the system, make sure you ask lots of questions.
  • Feel free to query the decisions, design and architecture.  But  do not start to immediately criticize  the way things are done. Remember there is always a reason things are the way they are.  Its most likely you, yourself will build something differently to the way you would have built it six months ago.
  • Respect the system in production. With the percentage of projects however brilliantly designed and coded never going into production, I always feel a sense of awe for any system (however badly built) out in the wild.


Happy Digging,

Ravi