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
