Molle Bestefich wrote:
Sure, that would help with understanding the call structure. But your angle of attack is utopian, since making up function names perfect enough to convey all needed information in the context of all callers, and always structuring code perfectly - especially when the code has to work exactly like Windows code - is practically impossible. And getting everybody to do it is even worse.
Teaching people to write good comments is infinitely easier - it's a simple case of banging 'em on the head and forcing them to write a comment every time they've done a piece of code that they know required cunning skill for whatever reason. You may need to perfect the english phrasing from some of the foreigners around here once they learn to actually write the comments, but that's a minor nit.
Teaching people to write well structured code is definitely much harder, as sloppy programmers can be easily trained to write better comments about their badly structured code.
Add all the great comments you like, but you still actually have to read the code and understand it to figure out how to fix it.
So, IMO, you're better off striving for the Utopian goal of well structured code that trying to make everybody understand what your reason or intention was when you were writing the code, as in the end you must understand the code and all it's subtleties anyway.
Mike