[Tutor] Documentation concerns.

[Magnus Lyckå]

At 06:40 2003-05-23 +0000, roy ollis wrote:
>if the code keeps changing would heavily commenting the code with 
>explainations and examples work as a form of documentation.

Shrug! I for one don't believe documentation gets better because
you put it in the source code, or that the source gets better when
you fill it with comments. Obviously, some documentation, such as
method names are parameter lists can be extracted from the source
code itself, but as I just wrote in another mail, the structure of
the source might not be the best structure to explain the code.

For sensible ideas on how to write comments in code, I refer to
Kernighan and Pike: "The Practice of Programming".

Also, I think Parnas was right in his ideas about modularity and
interfaces. It might be better if you *don't* look in the source
code for a module you are to use. The only thing you can rely on
anyway is the documented interface. The python developers must be
free to modify the implementation, and if you read that code, and
made assumptions about the implementation that weren't in the
documentation, your code might be depending on something that
won't be there in the next version of Python...

The typical consequence of putting a lot of comments in code that
changes a lot is that the comments and the code gets out of sync.

Where do you find the Library Reference lacking?

There are shortcomings in some areas like Tkinter, but since
Tkinter it fairly thin wrapper over Tcl/Tk, it's rather point-
less to put the docs in the source there.

Something you might find useful to learn how to use different
modules is the python test code. Look in the Lib/test directory.
The great thing is that the test code and the actual module code
doesn't get out of sync, because that would cause the tests to
fail. This is a huge advantage over any "dead" code comment. The
doctest module is a way to combine the both though.

Of course, there is never any guarantee that the test code is
100% complete, but that is also an area where you people could
be useful. Supply more tests if you find them lacking, or write
your code snippets to tutor in a format which is usable for
doctest. That would also be a suitable format for email.

>  if you wanted to see how something works just look at the source or .py 
> files.

I suggest that you look at test_generators.py if you want to
learn about generators for instance. Really: You should take a
look at that. Unfortunately, the test files are of varying quality.
I think that in general, the more recent are often more useful
than the older ones. I wish they were all like test_generators.py.


--
Magnus Lycka (It's really Lyckå), magnus@thinkware.se
Thinkware AB, Sweden, www.thinkware.se
I code Python ~ The shortest path from thought to working program