understanding someone else's program

[C. Ng]

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.

[Ben Finney]

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

[Joel Goldstick]

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

[Jean-Michel Pichavant]

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.

It may take a lot of time depending on how good the current code is.

JM

-- IMPORTANT NOTICE:

The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you.

[William Ray Wing]

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

[Chris Angelico]

On Sat, Nov 16, 2013 at 12:49 AM, Jean-Michel Pichavant
<jeanm...@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

[Denis McMahon]

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, denismf...@gmail.com

[Laurent Pointal]

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...@laposte.net