understanding someone else's program

C

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

Joel Goldstick

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


Sadly the case for the majority of software any of us will be involved
with maintaining.


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

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

Chris Angelico

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
 
D

Denis McMahon

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

Laurent Pointal

C. Ng said:
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.
 

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments. After that, you can post your question and our members will help you out.

Ask a Question

Members online

No members online now.

Forum statistics

Threads
473,733
Messages
2,569,440
Members
44,830
Latest member
ZADIva7383

Latest Threads

Top