Understanding other people's code

[Albert van der Horst]

In article <b023f6e6-a11d-4d05-a126-e3cc49cb367e at googlegroups.com>,
Azureaus  <lo0446 at my.bristol.ac.uk> wrote:
>On Friday, 12 July 2013 15:22:59 UTC+1, Azureaus  wrote:
<SNIP>
>
>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.

If the code is really tidy, it is possible to understand a function
using only the *documentation* (not the code itself) of any function
or data it uses. In oo you also need a context about what an object
is supposed to do. The next step is to proof for yourself that the
function exactly does what is promised in its own documentation.

And you get nowhere without domain knowledge. If you're in railways
and don't know the difference between a "normal" and an "English"
whathaveyou, then you're lost, plain and simple.

Don't treat the original comment as sacred. Any time it is unclear
rewrite it. You may get it wrong, but that's wat source control
systems are for. If at all possible, if you add a statement about
a function, try to add a test that proves that statement.

Anytime you come across something that is unsufficiently documented,
you document it tentatively yourself, keeping in mind that what
you write down may be wrong. This does no harm! Because you must
keep in mind that everything written by the original programmer
may be wrong, there is actually no difference! Now study the places
where it is called and check whether it makes sense.
This an infinite process. After one round of improvements you
have to go through everything again. I've got pretty bad stuff under
control this way.

You'll find bugs this way. They may or may not let you fix them.

There is however not much point in "working in" by reading through
the code. Time is probably better spent by running and studying, maybe
creating test cases.

Trying to understand any substantial code body in detail is
a waste of time.
For example: I once had to change the call code of the gcc compiler
to be able to use a 68000 assembler library (regarding which register
contain what data passed to the function). There is absolutely no
point in studying the gcc compiler. You must have an overview
then zoom in on the relevant part. In the end maybe only a couple
of lines need change. A couple of days, and a pretty hairy problem
was solved. (The assembler library was totally undocumented.
Nobody even tried to study it. ).

There is an indication that the original programmer made it all very
easy and maybe you go about it not quite the right way.
If you have a tower of abstractions, then you must *not* go down
all the way to find out "eactly" what happens. You must pick
a level in the middle and understand it in terms of usage, then
understand what is on top of that in terms of that usage.
That is how good programmers build there programs. Once there is
a certain level they don't think about what's underneath, but
concentrate on how to use it. If it is done really well, each
source module can be understood on its own.

All this is of course general, not just for Python.

>Thanks!
-- 
Albert van der Horst, UTRECHT,THE NETHERLANDS
Economic growth -- being exponential -- ultimately falters.
albert at spe&ar&c.xs4all.nl &=n http://home.hccnet.nl/a.w.m.van.der.horst