Understanding other people's code

[Peter Otten]

L O'Shea wrote:

> Hi all,
> I've been asked to take over a project from someone else and to extend the
> functionality of this. The project is written in Python which I haven't
> had any real experience with (although I do really like it) so I've spent
> the last week or two settling in, trying to get my head around Python and
> the way in which this code works.
> 
> The problem is the code was clearly written by someone who is
> exceptionally good and seems to inherit everything from everywhere else.
> It all seems very dynamic, nothing is written statically except in some
> configuration files. Basically the problem is I am new to the language and
> this was clearly written by someone who at the moment is far better at it
> than I am!
> 
> I'm starting to get pretty worried about my lack of overall progress and
> so I wondered if anyone out there had some tips and techniques for
> understanding other peoples code. There has to be 10/15 different scripts
> with at least 10 functions in each file I would say.

That sounds like the project is well-organised and not too big. If you take 
one day per module you're there in two weeks...

> Literally any idea will help, pen and paper, printing off all the code and
> doing some sort of highlighting session - anything! I keep reading bits of
> code and thinking "well where the hell has that been defined and what does
> it mean" to find it was inherited from 3 modules up the chain. 

As you put it here, the project is too complex. So now we have a mixed 
message. Of course your impression may stem from lack of experience...

> I really
> need to get a handle on how exactly all this slots together! Any
> techniques,tricks or methodologies that people find useful would be much
> appreciated.

Is there any documentation? Read that. Do the functions have docstrings? 
import the modules (start with the main entry point) in the interactive 
interpreter and use help():

>>> import some_module
>>> help(some_module)

Or use

$ python -m pydoc -g

and hit "open browser" (the project directory has to be in PYTHONPATH).

See if you can talk to the author/previous maintainer. He may be willing to 
give you the big picture or hints for the parts where he did "clever" 
things.

Try to improve your Python by writing unrelated scripts.

Make little changes to the project (add print statements, invoke functions 
from your own driver script, make a local variable global for further 
inspection in the interactive interpreter using dir() -- whatever you can 
think of.

The latter should of course be done in a test installation rather than the 
production environment. 

Rely on version control once you start making modifications for real -- but 
I think you knew that already...