Interesting piece of pie, Cessen! That is more or less the same technique I've been using in my Java projects lately. It's a very good thing and it really helps - not only with understanding the code I wrote myself a couple of months ago, but also as a programming aid while writing the actual code.
Don't know if any of you guys ever coded anything in Java, but one of the benefits is that if you write 'documentation comments' in all the right places in a class, you can use 'javadoc' later on to generate automatic documentation for all classes in a project. And the principles for this are exactly like PIE. Since the output of javadoc will be a series of html files intended to be read 'on the side' so to speak, you are automatically forced to write comments in a conceptual fashion.
Doxygen works similiar to javadoc for C++/C.
This coding convention guidelines was published last year about this
I use javadoc all the time, it produces HTML pages
that allow one to easily track down classes and methods
and see relationships between classes (iheritance, fields, usage of, related classes, etc.).. It reads the source code to find out a lot of it, and its really the only way to understand javacode, without it one would be totally lost..
Its also good to have an IDE to develop the source in, currently I'm using Netbeans with the code-completion feature, if you are unsure about a method you just type "classname." and up popsup the options and can find the class being used and the associated method, even jump to where the
method is defined in the source. Really makes coding Java easier.
Anyhow, this has nothing to do with Blender.. But if there was a
coding environment like this for working with blender, I would be in heaven!!
No, it doesn't have anything to do with Blender. I'd say I'm merely patting Cessens back by saying that a consistent commenting style is of utmost importance.