Velocity Reviews

Velocity Reviews (http://www.velocityreviews.com/forums/index.php)
-   Python (http://www.velocityreviews.com/forums/f43-python.html)
-   -   Understanding other people's code (http://www.velocityreviews.com/forums/t962677-understanding-other-peoples-code.html)

L O'Shea 07-12-2013 02:22 PM

Understanding other people's code
 
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 hadany 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 exceptionallygood 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 soI 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.

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. 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.

Chris Angelico 07-12-2013 02:46 PM

Re: Understanding other people's code
 
On Sat, Jul 13, 2013 at 12:22 AM, L O'Shea <lo0446@my.bristol.ac.uk> wrote:
> 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.



The first thing I'd recommend is getting yourself familiar with the
language itself, and (to some extent) the standard library. Then
you'll know that any unrecognized wotzit must have come from your own
project, so you'll be able to search up its definition. Then I'd
tackle source files one at a time, and look at the very beginning. If
the original coder was at all courteous, each file will start off with
a block of 'import' statements, looking something like this:

import re
import itertools

Or possibly like this:

from itertools import cycle, islice

Or, if you're unlucky, like this:

from tkinter import *

The first form is easy. You'll find references to "re.sub" or
"itertools.takewhile"; the second form at least names what it's
grabbing (so you'll find "cycle" or "islice" in the code), and the
third just dumps a whole lot of stuff into your namespace.

Actually, if the programmer's been really nice, there'll be a block
comment or a docstring at the top of the file, which might even be
up-to-date and accurate. But I'm guessing you already know to look for
that. :)

The other thing I would STRONGLY recommend: Keep the interactive
interpreter handy. Any line of code you don't understand, paste it
into the interpreter. Chances are it won't wipe out your entire hard
drive :) But seriously, there is much to gain and nothing to lose by
keeping IDLE or the command-line interpreter handy.

ChrisA

Peter Otten 07-12-2013 03:21 PM

Re: Understanding other people's code
 
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...




Eric S. Johansson 07-12-2013 04:04 PM

Re: Understanding other people's code
 
On Fri, 12 Jul 2013 10:22:59 -0400, L O'Shea <lo0446@my.bristol.ac.uk>
wrote:

> 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.
> 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.


glad to hear you're having a WTF moment (what's that function). Suggestion
would be index cards, each containing notes on a class. truly understand
what each parent class is in which methods are to be overloaded. Then look
at one child and understand how it. Work your way breadth first down the
inheritance tree.

Terry Reedy 07-12-2013 10:11 PM

Re: Understanding other people's code
 
On 7/12/2013 10:22 AM, 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.


If the functions are not documented in prose, is there a test suite that
you can dive into?


--
Terry Jan Reedy


CM 07-14-2013 06:58 AM

Re: Understanding other people's code
 
> 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!


Sure, as a beginner, yes, but also it sounds like the programmer didn't document it much at all, and that doesn't help you. I bet s/he didn't always use very human readable names for objects/methods/classes, either, eh?

> 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 least10
> functions in each file I would say.


Unless the programmer was really super spaghetti coding, I would think thatthere would be some method to the madness, and that the 10-15 scripts eachhave some specific kind of purpose. The first thing, I'd think (and having not seen your codebase) would be to sketch out what those scripts do, andfamiliarize yourself with their names.

Did the coder use this form for importing from modules?

from client_utils import *

If so, that's going to make your life much harder, because all of the namesof the module will now be available to the script it was imported into, and yet they are not defined in that script. If s/he had written:

import client_utils

Than at least you would expect lines like this in the script you're lookingat:

customer_name = client_utils.GetClient()

Or, if the naming is abstruse, at very least:

cn = client_utils.GC()

It's awful, but at least then you know that GC() is a function within the client_utils.py script and you don't have to go searching for it.

If s/he did use "from module import *", then maybe it'd be worth it to re-do all the imports in the "import module" style, which will break everything, but then force you to go through all the errors and make the names like module.FunctionName() instead of just FunctionName().

Some of that depends on how big this project is, of course.

> Literally any idea will help, pen and paper, printing off all the code and
> doing some sort of highlighting session - anything!


What tools are you using to work on this code? Do you have an IDE that hasa "browse to" function that allows you to click on a name and see where inthe code above it was defined? Or does it have UML or something like that?


Azureaus 07-15-2013 10:02 AM

Re: Understanding other people's code
 
On Friday, 12 July 2013 15:22:59 UTC+1, Azureaus 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 theway 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.
>
>
>
> 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. 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.


Thanks for all the suggestions, I'm afraid I didn't get a chance to view them over the weekend but I will get started with them this morning. I'm currently using sublime 2 for my text editor and tried to create a UML diagram using Pylint to try and get a map overview of what's going on. Unfortunately it seemed to map the classes into groups such as StringIO, ThreadPool, GrabOut etc.. rather than into the modules they belong go and how they fit together. Maybe this is just my inexperience showing through or I'm using theprogram wrong. If anyone has any 'mapping' programs they use to help them visualise program flow that would be a great bonus.

To be fair to who programmed it, most functions are commented and I can't complain about the messiness of the code, It's actually very tidy. (I suppose Python forcing it's formatting is another reason it's an easily readable language!) Luckily not blanked import * were used otherwise I really would be up the creek without a paddle.
Thanks!

CM 07-15-2013 07:13 PM

Re: Understanding other people's code
 
On Monday, July 15, 2013 6:02:30 AM UTC-4, Azureaus wrote:

> To be fair to who programmed it, most functions are commented and I can't
> complain about the messiness of the code, It's actually very tidy. (I suppose
> Python forcing it's formatting is another reason it's an easily readable
> language!) Luckily not blanked import * were used otherwise I really would be
> up the creek without a paddle.


Oh, good! OK, so then what you can think in terms of, in terms of a simplestrategy for getting clear without any fancy tools:

Learn what each module is for. In my own application programming, I don't just put random classes and functions in any old module--the modules have some order to them. So, for example, one module may represent one panel in the application, or all the database stuff, or all the graphing stuff, or some other set of logic, or whatever. One might be the main GUI frame. Etc.. So I'd get a notebook or file and make notes for yourself about what each module is for, and the name. Even tack a piece of paper above your workstation with the module names and a one line note about what they do, like:

MODULES:

Map_panel: Displays a panel with the map of the city, with a few buttons.
Dbases: Has all utility functions relevant to the database.
Utils: Has a collection of utility functions to format time, i18n, etc.

Now, there's a cheat sheet. So, if you come across a line in your code like:

pretty_time = Utils.GetPrettyTime(datetime)

You can quickly look at Utils module and read more about that function.

Does this approach make sense to at least clear the cobwebs?


asimjalis@gmail.com 07-16-2013 02:10 AM

Re: Understanding other people's code
 
On Friday, July 12, 2013 7:22:59 AM UTC-7, Azureaus 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 theway in which this code works.


Here are some techniques I use in these situations.

1. Do a superficial scan of the code looking at names of classes, functions, variables, and speculate where the modification that I have to make will go. Chances are you don't need to understand the entire system to make yourchange.

2. Build some hypotheses about how the system works and use print statements or some other debugging technique to run the program and see if you get the result you expect.

3. Insert your code into a separate class and function and see if you can inject a call to your new code from the existing code so that it now works with the new functionality.

If you have to understand the details of some code, one approach is to try to summarize blocks of code with a single comment to wrap your mind around it.

Asim

David M Chess 07-16-2013 06:38 PM

Re: Understanding other people's code
 
> 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.
> 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.

I'd highly recommend Eclipse with PyDev, unless you have some strong
reason not to. That's what I use, and it saves pretty much all of those
"what's this thing?" problems, as well as lots of others...

DC



All times are GMT. The time now is 10:53 AM.

Powered by vBulletin®. Copyright ©2000 - 2014, vBulletin Solutions, Inc.
SEO by vBSEO ©2010, Crawlability, Inc.