Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.python > #59508 > unrolled thread

understanding someone else's program

Back to article view | Back to comp.lang.python

Contents

  understanding someone else's program "C. Ng" <ngcbmy@gmail.com> - 2013-11-15 03:05 -0800
    Re: understanding someone else's program Ben Finney <ben+python@benfinney.id.au> - 2013-11-15 22:19 +1100
    Re: understanding someone else's program Joel Goldstick <joel.goldstick@gmail.com> - 2013-11-15 08:39 -0500
    Re: understanding someone else's program William Ray Wing <wrw@mac.com> - 2013-11-15 08:50 -0500
    Re: understanding someone else's program Chris Angelico <rosuav@gmail.com> - 2013-11-16 01:03 +1100
    Re: understanding someone else's program Denis McMahon <denismfmcmahon@gmail.com> - 2013-11-15 17:41 +0000
    Re: understanding someone else's program Laurent Pointal <laurent.pointal@free.fr> - 2013-11-18 23:42 +0100

#59508 — understanding someone else's program

Hi all,

Please suggest how I can understand someone else's program where
- documentation is sparse
- 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

Am using ERIC4 IDE.

Thanks.

[toc] | [next] | [standalone]

#59509

"C. Ng" <ngcbmy@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

[toc] | [prev] | [next] | [standalone]

#59516

On Fri, Nov 15, 2013 at 6:19 AM, Ben Finney <ben+python@benfinney.id.au> wrote:
> "C. Ng" <ngcbmy@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

[toc] | [prev] | [next] | [standalone]

#59518

On Nov 15, 2013, at 6:05 AM, C. Ng <ngcbmy@gmail.com> wrote:

> Hi all,
> 
> Please suggest how I can understand someone else's program where
> - documentation is sparse
> - 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
> 
> Am using ERIC4 IDE.
> 
> Thanks.
> -- 
> https://mail.python.org/mailman/listinfo/python-list

The other suggestions you have received are good places to start.  I'd add only one other - that you consider running the code inside an IDE and single-stepping through as you watch what happens to the variables.  As you get a better and better feel for what the code is doing, you can move up from single stepping to setting break points before and after places you are still scratching you head over.

-Bill

[toc] | [prev] | [next] | [standalone]

#59521

On Sat, Nov 16, 2013 at 12:49 AM, Jean-Michel Pichavant
<jeanmichel@sequans.com> wrote:
> If the documentation is sparse, writing the doc yourself is one way to dive into someone else's code. To begin with, you can stick to the function purpose, and for the WTF functions try to document the parameters and return values as well.

Agreed. I just had someone do that with my code - it was sparsely
commented, and he went through adding docs based on what he thought
functions did (based on their names and a cursory look at their bodies
- return values, particularly, were often documented by description,
which wasn't particularly useful with certain callbacks). Seeing where
he'd misdescribed something was a great way for me to figure out which
functions were poorly named, or at least begging for better comments.

If you have the luxury of working with the original programmer, that
would be something I'd strongly recommend. Even if you can't, try to
set some comments down; but be aware that false comments are worse
than none at all, so do notate which are your comments and which bits
you're particularly unsure of.

ChrisA

[toc] | [prev] | [next] | [standalone]

#59554

On Fri, 15 Nov 2013 03:05:04 -0800, C. Ng wrote:

> Hi all,
> 
> Please suggest how I can understand someone else's program where -
> documentation is sparse - 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
> 
> Am using ERIC4 IDE.

You just have to work through it working out what each line does.

Start with the inputs and give them sensible names, after all you 
presumably know where they come from and what they represent. Then you 
can see what operations are being performed on the input data, and 
presumably if you have enough knowledge in any relevant fields, may be 
able to determine that, for example, when the input 'x' is actually a 
temp in fahrenheit, then the math operation 'x=(x-32)*5/9' is really 
"convert temp from fahrenheit to centigrade".

As you do this add relevant comments to the code. Eventually you'll have 
code with sensible variable names and comments that hopefully describe 
what it does.

-- 
Denis McMahon, denismfmcmahon@gmail.com

[toc] | [prev] | [next] | [standalone]

#59914

C. Ng wrote:

> Hi all,
> 
> Please suggest how I can understand someone else's program where
> - documentation is sparse
> - 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
> 
> Am using ERIC4 IDE.

To help for documentation, you may test pycallgraph, eventually depgraph if 
there are multiple modules.


http://pycallgraph.slowchop.com/en/master/
http://www.tarind.com/depgraph.html

A+
Laurent.

-- 
Laurent POINTAL - laurent.pointal@laposte.net

[toc] | [prev] | [standalone]

Back to top | Article view | comp.lang.python

csiph-web