Reading others' code

Ye' old general discussion board. Basically, for everything that isn't covered elsewhere. Come here to shoot the breeze, shoot your mouth off, or whatever suits your fancy.
This forum is not for asking programming related questions.

Moderator: General Moderators

Post Reply
User avatar
Burrito
Spockulator
Posts: 4715
Joined: Wed Feb 04, 2004 8:15 pm
Location: Eden, Utah

Reading others' code

Post by Burrito »

I just wanted to get a feel for how you all read others' code. I just started a new job and have been thrown into a fire where I need to make some pretty hefty modifications to a custom CMS system that was built here. The system seems to have been written well and it's structured very well too, but oh my gawd is it a lot of stuff. It's entirely OOP with smarty templates which in some ways makes it harder to weed through. Here's why:

For starters there is very little commenting on the code and each page has included files which have required methods and properties that are used in 'local' classes. The tough part is following the rope from one end to another. Especially when you have objects being passed to the constructors of other objects and used as properties within those classes.

So here's my question: What practices do you use to follow code like this? Do you lay out some kind of roadmap so you have something to follow or do you just identify a task then try to pick your way through to accomplish that task?

I've been trying the latter with little success to this point.

In a way I also kinda feel like this code is trying to use a sledgehammer to push in a thumbtack. I understand that it needs to be very modular, but it took the author 1.75 hours to simply change a default selected value in a select box...that says something to me.

So how do you all do it?
User avatar
Christopher
Site Administrator
Posts: 13596
Joined: Wed Aug 25, 2004 7:54 pm
Location: New York, NY, US

Post by Christopher »

For me the most important thing is to find and document for yourself all of the conventions use in the code. I find the real differences are in conventions and usually not the concepts themselves. The programmer(s) who wrote the code you have to deal with used slightly different conventions than you do. Once you find out what they are then the coin will drop because you can map how you think about an application onto this code base.

Unfortunately you are going to need to trace through a bunch of code paths to get a sense of the shape of the thing. I would start at index.php and work my way thorugh the main requests -- then branch out to the less frequent ones. Then you can find the similarities and differences -- for example they may do things differently on the admin side than the public side.
Last edited by Christopher on Fri Jun 30, 2006 11:08 am, edited 1 time in total.
(#10850)
User avatar
RobertGonzalez
Site Administrator
Posts: 14293
Joined: Tue Sep 09, 2003 6:04 pm
Location: Fremont, CA, USA

Post by RobertGonzalez »

Sounds kinda silly, but what I do is comment the code. I read each line, figure out what it does, then add a comment to it. For classes, I usually add property and method descriptions (using something like phpDoc format) as well as expected parameters and types. Same for functions used. I also like to comment on dependencies and requirements, expected includes and what each include does (if the page name doesn't describe it right).

It can be time consuming, but it is usually only time consuming once.
User avatar
Weirdan
Moderator
Posts: 5978
Joined: Mon Nov 03, 2003 6:13 pm
Location: Odessa, Ukraine

Post by Weirdan »

I would first run the phpDocumentor over entire source tree. Even if there's no phpdoc comments, it would produce class hierarchy tree. Also there's PHPXref - handy source tree browser.
User avatar
MrPotatoes
Forum Regular
Posts: 617
Joined: Wed May 24, 2006 6:42 am

Post by MrPotatoes »

get a notebook and get ready to write stuff down

what i do is i usually go ahead and take people's code and pick one area onthe screen i want to screw with. then i go from there. see where things are coming in and going out. full text searches are very helpful here.

for instance i needed to change something in zencart. my boss wanted me to make it go from all products to a heading with the manufacturer name and all thier products sorted.

well i found the fine (thank god something in that system is named decently) and i just started to echo crap to see where it was being called, shown and all that junk. after i did that i commented out stuff to make sure i knew what was going on. from there i looked into the other files that were including it and it was including and seeng what was being done. once i figured everything out i started coding and got it done. and if i don't say so myself it looks fab-u-lous
User avatar
Chris Corbyn
Breakbeat Nuttzer
Posts: 13098
Joined: Wed Mar 24, 2004 7:57 am
Location: Melbourne, Australia

Post by Chris Corbyn »

Weirdan wrote:I would first run the phpDocumentor over entire source tree. Even if there's no phpdoc comments, it would produce class hierarchy tree. Also there's PHPXref - handy source tree browser.
I agree on running PHPDoc over the code. It'll give you an overview of what's going on.

I tend to quite literally just follow through the code bit by bit, tracking where each function/method call takes the logic. Hopefully you'll spot things that tend to lead down the same path and get a feel for what some of the less obvious compnents do. So essentially what I'm saying is that I don't do it any scientific way... I just follow the logic :P
timvw
DevNet Master
Posts: 4897
Joined: Mon Jan 19, 2004 11:11 pm
Location: Leuven, Belgium

Re: Reading others' code

Post by timvw »

- When i'm really lucky, the author left a couple of documents that explain the problem, solution, and actual implementation (as if this would ever happen :p)

- When i'm lucky i can contact the author and ask him the things i would have wanted to find in the documents mentionned above (this has happened a couple of times)

- When i'm not that lucky at all, there is no documentation, and the author(s) have left planet earth... Then i start reading the code from start to beginning (i write down every include file and every user-function call). I try to understand the code...

With this first idea of the code i lookup the user-functions and repeat the process all over.
This time, i will verify if the code in the user-function still matches with this first idea...
If it doesn't, i modify the first idea...
I repeat this process over and over, untill i've plunged through (almost) all of the code...

With larger programs this might take a week (or even more)..
If you don't want others to suffer the same way you just did last week(s) you'll probably want to write what you've found out..
Roja
Tutorials Group
Posts: 2692
Joined: Sun Jan 04, 2004 10:30 pm

Post by Roja »

In working on the 30k line+ monstrosity that is Blacknova Traders, here is the approach I've taken - for better or worse.

1. Focus on bug fixes first. If you get a bug, fix it. This will allow you to dive into problem areas first, which often are an indication of the overall state of the code.

2. Reformat the code consistently between bug fixes. Bracket layout, spaces v. tabs, variable/function naming, these things make no difference to the functioning of the code, but make all the difference in the world to readability. But don't do it over bug fixes!

3. Climb the ladder. Start with cleaning up piles of procedural code into functional units. Once that is done, you should begin to see clear objects and classes developing. After that, start building tests for them (or vice versa). Each file you do this to will improve (slowly), while staying functional - keeping you ahead of the game for #1.

4. Between 2 and 3, you should see clear patterns, and be able to refactor and redesign chunks of code. The beauty of having functional units, is that you can start to compete with them. Do I really need 200 lines to process an INI file? Probably not. Shouldn't users be an object, complete with properties and behaviors? You betcha.

I'm doing #3 and #4, while focusing on #1 now. Its a very long-term approach, but it gives me both functional status at most points, and the learning process of where OOP 'grows' out of Procedural. I've mostly done OOP from a 'clean slate', so I must say its an interesting process.

As a note about phpdoc, it does little for highly procedural code, just giving the function name, arguments, and files they are contained in.. not nearly as useful as it is for well-designed OOP code.

At any rate, good luck. Its not easy.
Post Reply