Antonio Bleile wrote: >Hi, > >Scrive Gerrit Voss <[EMAIL PROTECTED]>: > > >>[...] >>- Documentation >>[...] >>But the major problem I see is the imperative, at least for me, to spend >>time on documentation and especially where to get the time from. If >>anybody has a good idea how to do this I'm all open to suggestions, >>except to those that involve physical violence ;-). >> >> > >It would be useful to have at least a documentation of >each method (including parameters) and each member variable >of all classes and a brief description for each class. >Just a brief description of what the method does and >what a member variable is there for. It requires a minimum >of extra time and should be somehow part of the programming >process. I know developers hate it (I'm also quite lazy on >this), but you really just need a little extra discipline >to do it :-) The developers itself actually would benefit >of such kind of documentation in terms of time saving. >I almost always have to look at the code to get an idea of >what a method does which takes up some time... > >So I suggest you should define a standard header (some doxygen style >of your choice, pick an existing "syle guideline") and every >new method you guys write should be commited containing a >minimum of documentation. And in the spare time you might >document other older methods (at least the important ones..)... > > I agree completely. This is one point I forgot to make. There are too many classes and members that have no documentation at all. The documentation doesn't even have to be complete, just add a little comment that says "This class does X". That would help tremendously.
One way to make this a little easier IMHO would be to use the doxygen commenting style where you put the documentation in the header right next to the class, method, and member declarations. I know that some people thing this makes it harder to see the methods through the documentation, but I think that is a problem I would love to have with OpenSG. By putting the documentation right there with the declarations it is very easy to see what is documented and what isn't. It is also nice because you can read the header and see all the documentation about how to use the class. The first time I open up a class header and say "I can't see the methods through all this documentation" will be the happiest day of my OpenSG-using experience. -Allen > > >>[...] >>We also should find a way to have some usable issue/bug trackers. I >>don't know why the ones sourceforge provides did not catch with OpenSG. >> >> > >Bugzilla? > > > >>[...] >> >> > >Regards, > > > Toni > >---------------------------------------------------------------- >This message was sent using IMP, the Internet Messaging Program. > >------------------------------------------------------------------------- >Using Tomcat but need to do more? Need to support web services, security? >Get stuff done quickly with pre-integrated technology to make your job easier >Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo >http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642 >_______________________________________________ >Opensg-users mailing list >[email protected] >https://lists.sourceforge.net/lists/listinfo/opensg-users > > > ------------------------------------------------------------------------- Using Tomcat but need to do more? Need to support web services, security? Get stuff done quickly with pre-integrated technology to make your job easier Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642 _______________________________________________ Opensg-users mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/opensg-users
