In article <b023f6e6-a11d-4d05-a126-e3cc49cb3...@googlegroups.com>, Azureaus <lo0...@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@spe&ar&c.xs4all.nl &=n http://home.hccnet.nl/a.w.m.van.der.horst -- http://mail.python.org/mailman/listinfo/python-list
