Hi,
We often come across situation that we need to maintain other people's source code. But this is too often painful. To earn a living, you can't avoid it. So I'd like to know (except reading line-by-line and using a source analyser) what is the best way to comprehend what other people are trying to do? especially C/C++?
Thanks
Jack

Massive amounts of comments

There is a book on the subject -- Code Reading: The Open Source Perspective by Domidis Spiellis.

There are tools to aid browsing C such as ctags, which you would probably already use. Web2c or vgrind could typeset the sourcecode to make it easier to study. A program called cdecl can take a complicated c declaration and translate it into english. The same program called as c++decl will do the same for c++ declarations.
You can also use the idutils indexing tools

I assume that you are talking about understanding code that has already been written, the miscreant has not deigned to add comments to the source or over time they have become a garbled meaningless view of the said programmers social life. In other word reality...

• First try to understand what it actually does.
• Next try to understand what it should do.
• Read specifications and designs (but with a pinch of salt, since the programmers probably treated them with the same lofty respect they had for comments)
• Draw your own high level design which lumps of code (occasionally called classes in C++) do what
• Find the area of the programme that you need to focus on, presumably there is an area that doesn't quite work as well as the original programmers believed that it would (sometimes referred to as a feature, and by other less understanding folk, a bug)
• Draw your own design of the order that methods are called and what each method is meant to do.
• Once you have narrowed down an area for improvement, focus on the source code

You may now be ready to change some code, go ahead but remember two important rules

1. Use a version control system so you can backout your changes if they don't work
2. Comment your changes, just because no one else commented the code doesn't mean that you shouldn't

But essentially build up you understanding of the system in small incremental steps.

Just as graemef suggested, use version control. Then dive right in. Start in main, make some stupid change like adding a cmdline param. Compile. Run. Make the param control some aspect of the code. Pick something simple. A flag, a class property, something that controls the flow a bit. Compile. Run. Branch out, make a bigger change. Add some minor functionality. This will force you to interact with other portions of the code. Compile. Run. After a few iterations of this nonsense, you will be one with the code. Compile. Run. Restore original version and make the change(s) you really need.

When your coding your "own" program, always consider your collegue in the future, having to maintain your code.
and ...
Coding standards are for loser, not for you, right?
Standards limit your creativity, right?
The more compact and efficient your program, the better, right?

You would not want the topic starter to refer to your code?

Tell the other people to use correct coding syle, and use comments.

Ah, but the problem with that is that first it has already been coded, and secondly what is a correct coding style?

Correct coding style is finding something and sticking with it. But I'm sure you hear them all the time.

*Avoid using more than three levels of code.

If your code looks this

if code == crap then{

if code === poop then{

if code == excrement then{

if code == bowelmovement then{
}
}
}

It might be time to start using some switch statements or sp,e AND,NOT type conditional statements.


Avoid recursive functions like the plague

SuperOverLongVariableype disaster;

funcEatupMemory(disaster_exit){

funcEatupMemory(disaster += 1);

}


And ofcourse most importantly of all clean up after yourself.

int onceloved;
int *nowlonelyandforgotten;


onceloved = going_to_leave_you_soon;

nowlonelyandforgotten = &onceloved;

*nowlonelyandforgotten = NULL; //



Or something like that anyways. Maybe if you start with the lowest possible expectations it gets easier to read code?

Everyone really has their own take on what correct coding style is.
Do a google search for coding styles and choose one that you can adapt to a style you like, but don't hold others to keep to that style. If that person has NO style, however, you may want to have a talk with them. Also, there are programs out there to auto-format your code to make it readable(how useful they are, I don't know).

I found "GNU indent" to be extremely helpful in such situations. I recommend it as the very first step when inheriting code from someone else who did not hold on to any style.

Or switch to a language that uses plain english words like AND instead of cryptic symbols like &&. Then you won't need two lines of comments for one line of code. The code almost comments itself.

Know what you mean (http://opencobol.org/).
But here (unix/linux world) you're not taken serious when your not coding in a compact & criptic language. Never understood why.

People code in Perl, think it's too criptic, so they invent Python and/or Ruby, and all that time "gool old rexx" is lying there on the shelf, and nobody cares to pick it up....

Indeed and that is the problem. Don't get me wrong I believe having a consistent style is importent but one man's standard is another man's guide, and may therfore be ignored.

For example I wouldn't think of coding binary tree navigation routines without using recursive functions. However...

But this thread appears to be digressing from the what can we do to understand existing code to what should we do to make code easier to understand. As I said earlier to understand an existing application I wouldn't initially dive into the code rather I'd start off by trying to get an understanding of the bigger picture.

You're right , but I just can't help but think of the generic safe blanket answer, which I'm sure is floating in the back of some your heads.

Make yourself smarter.



Puzzle solving, reading a book, learning in general helps alot even if its completely unrelated to programming. You can't predict the future. Theres no way of telling what horrible or convuluted code you might have to look at. What if there is no discernable purpose or big picture? What if the person just added in some random drunken code? Then you have no choice but to restructure piece by piece. Besides coding often, you have to keep a keen mind. And it doesn't hurt to change the subject every once in a while. You CAN get bored of coding.

Think code analysis like spell check. You read a paper backwards to do a thorough check, because 'your understanding' might actually cause you to glaze over details. Do a flow chart(noone really mentioning this strangely), follow the connections between functions. Piece by piece I say.


After all isn't programming a series of trivial tasks?