On Thu, Jul 23, 2009 at 2:09 AM, David ?Bombe? Roden<bombe at pterodactylus.net> wrote: > On Thursday 23 July 2009 01:12:15 Evan Daniel wrote: > >> The method HTMLEncoder.encode() sounds like it ought to do that. ?Let's take >> a look at the Javadoc: >> >> encode >> >> public static java.lang.String encode(java.lang.String s) > > I guess I?m the only having to take the blame for that. HTMLNode and consorts > have been committed by me. And though in a local version all of the HTML* > classes do have javadoc comments those seem to have been created after I > committed them to Freenet. > > Since the time I wrote those classes I have gone over to javadoc commenting > everything I write as I write it. As you already have noticed documentation is > not a strong side of developers so that even if I had committed those files > with documentation that documentation would now be largely out of date so that > it might even be wrong. That would be equally helpful as having no > documentation at all. :) > > I?m aware that the HTMLEncoder class was merely an example that you used to > demonstrate what?s wrong the code base in general. Unfortunately there?s not > really a way to force developers to write (good!) documentation for the stuff > that they do. > > I have configured my Eclipse to perform javadoc validation on everything, > including checking for malformed comments and the like. And I?ve grown opposed > to files that show any warning in Eclipse so that at least the code I?m > committing in the future will have meaningful javadoc comments. I?m urging > everyone to do the same but?as I already said?you can?t enforce it.
Well, if you're sufficiently motivated, you can enforce it -- simply don't apply patches that don't include sufficient documentation. That's harsh enough that I'm not sure it's worth it, though. And yes, the HTMLEncoder was merely the most recent example I'd been frustrated with; it's no better or worse than most of the rest of the code I've looked at. If you'd commit your comments on HTMLEncoder, I'd appreciate it. Specifically, I'm trying to figure out whether it's supposed to take well-formed, non-malicious strings and format them so they display properly in HTML, or whether it should also be filtering malicious strings so that they don't screw up the page. Not being an HTML expert, I'm uncertain whether it does the latter. It worries me that it doesn't filter the ascii control characters. The best citation I can find on that says that aside from tab, CR, and LF, they shouldn't appear in HTML documents: http://www.w3.org/MarkUp/html3/specialchars.html However, that's for HTML 3. HTML 4 specifies everything in reference to character encodings, and I'm having trouble answering the question for it. Perhaps someone who knows HTML better than I do could chime in? My personal habit in documenting involves more comments than most of Freenet has. It tends towards big blocks of text rather than Javadoc since I rarely run the javadoc engine against my own code -- my projects tend to be small enough I usually have all the relevant files open in gvim anyway. I think credit for that goes to my Assembly professor, who wouldn't even bother grading things that didn't have sufficient comments. Of course, I'm not particularly good about keeping the comments up to date, which is sometimes better and occasionally worse than no comments. Evan Daniel
