U++ forum: Welcome to the forum

Re: A Few observations on U++ (lack of) documentation [message #5699 is a reply to message #5692]

Tue, 10 October 2006 15:42

arixion
Messages: 27
Registered: October 2006
Location: Southeast Asia

Promising Member

luzr wrote on Tue, 10 October 2006 15:23

Actually, I think this was discussed here several times. One visible result of discussion is that we have now all these tutorials and that about 50% of U++ now has reference documentation (should be about 70% at the next major release).

So the work is in progress. The only topic I (as "leading developer") am reluctant to do is to start using comments in the code. I think that the good code does not need comments other that commenting the purpose of class and public methods (and MAYBE something more if implementation is unusual). I plan to introduce such Assist++ improvements in future releases that will make this information as easily accessible as if it was written as comments.

As for adding .usc description scripts for less frequently used classes, I agree, it is on ToDo list. (BTW, this is not the same as "reference/USCControl" - that one is mere example how to create .usc script for your own custom control). Maybe somebody could step in and contribute a bit Smile

luzr,

hmmm, I was actually referring to comments on class and publci methods, albeit those in teh source files. Perhaps, it is because I am using the release version (605) that I don't see the comments in the code? Ok, to be fair, most of the class methods are quite descriptive, but some do need a little elaboration:

1)those fns that require "flags" need to have extra elaboration on what these flags are.

2) fns which use abbreviations - just off the cuff - like RichTextCtrl's "GetSb": what is "sb"? Or say, TabCtrl's "ChParam"?

3) btw, I seem to see that the USC scripts seem merely partial copies of the CPP sources; what's the use of USC then?

4) I think a good way to test the descriptiveness of variable names is to look at the code from the point of view of a newcomer, and see if you understand the purpose of each class property and method completely at first go. For example, looking at most code files (even of the devt version), I can't tell at first glance what the various enums are meant for. And if there is no such code documentation, then at least u should avoid giving one-letter names for arguments e.g. "Button & b, int r". After all, arguments can be a very good clue to what the method is about, or at least direct users of the libraries will know the appropriate arguments to apss the functions. This is especially important, I feel, if you want to have a black-box interface to the library. I mean, let's have an analogy: say we have a vending machine with buttons that are labelled with no pictures and no text except "a", "b", "c", "d" and so on. A person who wishes to sue this machine will probably waste alot of money before he gets what he wants, unless s/he is extremely lucky. I hoep you can see my point.

But anyway, I do think UPP is a great effort, and the fact that I'm willing to criticize it this strongly shows really how much I wish it to improve. I seriously think a little more documentation would serve it properly. And btw, for gui_tutorials, u should probably include a brief tutorial text to go with each tutorial. Learning from source-code is seriously quite hard, especially for complex controls like SQL controls where a beginner to DB programming might not understand SQL terminology u take for granted.

Report message to a moderator