Thanks for your comments as well Stefan. I will consider them as I make my efforts to document some of OpenJUMP's source code.
SS On 8/31/06, Stefan Steiniger <[EMAIL PROTECTED]> wrote: > once more i agree with Larry, > > your example doc is too detailed, because usually after half a year you > will be able to read normal method headers. (but i can remember that in > the very beginning I also commented everything for myself .. but after 2 > months..) > Although i sometimes miss also good documentation in jump and dislike > chained instructions which sometimes include even teh creation of new > objects => so, Jon is realy a java wizard ;) > > If you are working with eclipse you will see that eclipse has an > autocomplete function which automatically adds javadoc descriptions to > your methods and you only need to fill it. > > Whats is important is sometimes some code in a method itself describing > what follows in a few words for the next lines. And whats useful as well > are hints for useful parameter values or which class or method may > deliver your needed input parameter. > > stefan > > Sunburned Surveyor wrote: > > >Thanks for the constructive criticism Larry. :] > > > >I still like the detailed explanation, but you are right about > >including notes of the return value and parameters. I may remove > >those. > > > >I realize this is a style many programmers have a problem with. (But > >then again, that's probably why so many open source projects lack good > >documentation. Programmers aren't always that fond of writing.) That's > >why I think I'll keep it separate from the CVS. I had imagined it as a > >good place to send those wanting to understand OpenJUMP's code. I know > >those type of comments would have helped me. > > > >SS > > > >On 8/31/06, Larry Becker <[EMAIL PROTECTED]> wrote: > > > > > >>Hi Sunburned, > >> > >> Other developers may feel differently, but for me the comments you added > >>are of the sort that many college programming instructors would find > >>objectionable. Many coders find that putting in comments that reiterate > >>what the code already says unnecessarily clutters the source code. The > >>comments also do not follow Javadoc syntax. IMHO the comments should simply > >>state the purpose and leave out unnecessary mention of number of parameters > >>and return values. > >> > >>just my opinion, > >>Larry > >> > >> > >>On 8/31/06, Sunburned Surveyor <[EMAIL PROTECTED]> wrote: > >> > >> > >>I sent a source code file for OpenJUMP with some revised comments > >>yesterday. I realized this morning I used the wrong type of single > >>line comment marker. The attached file has fixed this problem. > >> > >>Sorry about that. > >> > >>The Sunburned Surveyor > >> > >> > >>------------------------------------------------------------------------- > >>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 > >> > >>_______________________________________________ > >>Jump-pilot-devel mailing list > >>Jump-pilot-devel@lists.sourceforge.net > >>https://lists.sourceforge.net/lists/listinfo/jump-pilot-devel > >> > >> > >> > >> > >> > >>------------------------------------------------------------------------- > >>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 > >> > >>_______________________________________________ > >>Jump-pilot-devel mailing list > >>Jump-pilot-devel@lists.sourceforge.net > >>https://lists.sourceforge.net/lists/listinfo/jump-pilot-devel > >> > >> > >> > >> > >> > > > >------------------------------------------------------------------------- > >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 > >_______________________________________________ > >Jump-pilot-devel mailing list > >Jump-pilot-devel@lists.sourceforge.net > >https://lists.sourceforge.net/lists/listinfo/jump-pilot-devel > > > > > > > > > > > ------------------------------------------------------------------------- > 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 > _______________________________________________ > Jump-pilot-devel mailing list > Jump-pilot-devel@lists.sourceforge.net > https://lists.sourceforge.net/lists/listinfo/jump-pilot-devel > ------------------------------------------------------------------------- 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 _______________________________________________ Jump-pilot-devel mailing list Jump-pilot-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/jump-pilot-devel
