Understanding a software system

Question

I recently became part of a complex embedded project team for which I will be developing a part. For the part which is my responsibility there is only old code and not much documentation.

I am keen to make a good start but shyness and fear of appearing stupid makes it difficult to ask questions. How to ask questions ?

I wanted to ask what techniques do you guys use to understand a project ? I mean there are of lots of technical details which one must remember and keep in context in order to make a design. Your read the code and get some facts but how to move ahead ? For instance you read the code and the document(s) and get some facts A and fact B . How to reach suitable conclusion X for which you may or may not have needed to take into account facts C and D also ?

Answer 1

Reading the code is balanced by writing the documentation.

Write the documentation that your replacement will need. Imagine someone who knows less than you. Explain it for that person.

When you cannot explain something to your replacement, ask questions.

When you have a complete description, you will "know" the system.

And you will have produced complete documentation.

Answer 2

Code-reading can be particularly difficult if there is not enough documentation and the code is poorly documented and badly written. I guess the best way now is to find the entry point of the code, and slowly understand its flows and what data it uses. I would keep a look out for

1. Structure - are there any partitioning of entities/system? Where in the code (and how) do they communicate with each other?

2. Data - what sort of structures are used to hold the global data? How are the data accessed and saved?

3. If you are doing C or C++, it is also important to find out how memory is handled and for C++ (and other related non-managed memory OOP languages, I guess), how are object ownership contained.

4. Since it is an embedded project, are there any non-standard code or coding constructs used?

Answer 3

You don't mention what kind of tests exist. If there are test cases, modify them and trace how this would affect the end result.

Answer 4

You might want to look at diagrams which give the entire picture of the logical structure of the system, like, for example, looking at class diagrams in an OOP system would be of great help. Looking at the design diagrams of large and complex apps gives you a clear understanding of how the internal modules of the system are organized and this way its makes the task of figuring out what functionality does a particular piece of code does much much easier. In the absence of diagrams, you're best bet would be to start from the entry point of the app, like main() and proceed from there while you draw(literally draw or write down on paper) your own conclusions about the system(this way you can have your own documentation) and ask your peers if they're correct.

Answer 5

My experience is that it's best to start with some kind of task -- a bug fix or other small change. That will provide focus to your learning. I find it hard to read through a binder or sift through pages of source code or documentation without having a way to apply it.

If you have a sandbox where you can play with changes that you've made without messing up the code base, that can be even more helpful.