understanding someone else's program

[Joel Goldstick]

On Fri, Nov 15, 2013 at 6:19 AM, Ben Finney <ben+python at benfinney.id.au> wrote:
> "C. Ng" <ngcbmy at gmail.com> writes:
>
>> Please suggest how I can understand someone else's program
>
> Welcome to this forum!
>
> I sympathise with this query. Much of the craft of programming is in
> understanding the code written by other programmers, and learning from
> that experience how to improve the understandability of the code one
> writes.
>
> In general, the answer to your question is: Read a lot of other people's
> code, preferably by the side of the programmer who wrote it. Experiment
> with a lot of code written by others, and test one's understanding by
> improving it and confirming it still works :-)
>
>> where
>> - documentation is sparse
>
> Sadly the case for the majority of software any of us will be involved
> with maintaining.
>
>> - in function A, there will be calls to function B, C, D.... and in
>> those functions will be calls to functions R,S,T.... and so on so
>> forth... making it difficult to trace what happens to a certain
>> variable
>
> This is normal modular programming. Ideally, those functions should each
> be doing one conceptually simple task, with a narrowly-defined
> interface, and implementing its job by putting together other parts at a
> lower level.
>
> Is there something particular about these functions that make them more
> difficult than good code?
>
> --
>  \          “Generally speaking, the errors in religion are dangerous; |
>   `\    those in philosophy only ridiculous.” —David Hume, _A Treatise |
> _o__)                                           of Human Nature_, 1739 |
> Ben Finney
>
> --
> https://mail.python.org/mailman/listinfo/python-list

Much more time is spent figuring out old code than writing new code!
Python docstrings help a little.  Do you know about a utility called
pydocs?  If you don't, read about it.  Using pydocs you can produce
documentation for all the modules you need to understand.  It will
pull out the docstrings at the top of the module,and for each method
and function.  Normally, that level of documentation won't be good
enough to satisfy the needs of a new reader, so go through each
function and understand them one at a time.  Add to the docstrings.


-- 
Joel Goldstick
http://joelgoldstick.com