Member, method/function/procedure and class comments can easily fall in the same area you're talking about with these comments, and I don't think too many folks get overly lost with those...
You've got a nice point, but my $0.02 is that I'd rather see the developers working other issues unless this is a seriously low-hanging fruit fix. > -----Original Message----- > From: Merrill Cornish [mailto:[EMAIL PROTECTED] > Sent: Friday, August 27, 2004 10:44 AM > To: Holmes, Jim; [EMAIL PROTECTED]; [EMAIL PROTECTED]; > [EMAIL PROTECTED] > Subject: RE: [Nant-users] Properties Descriptions > > > Jim, > > >>> How would this differ from using XML comments in the build files? > > Clumsiness, or lack thereof. > > <!-- location of the MSI installation log --> > <property name="msiexec.log" > value="${sys.os.folder.temp}msiexec.log" /> > > or > > <property name="msiexec.log" > value="${sys.os.folder.temp}msiexec.log" /> > <!-- location of the MSI installation log --> > > versus > > <property name="msiexec.log" > value="${sys.os.folder.temp}msiexec.log" > comment="location of the MSI installation log" /> > > XML comments are verbose and stand on a level with the > elements they are supposed to be commenting on. Therefore, > it's not always clear who they apply to. > > Most programming languages not only have provision for > stand-alone comment lines (such as <!--...--> provides for > XML) but also embeded (e.g., /*...*/) or end of line (e.g., > //...) comments that are clearly associated with a single > statement or even a single expression. > > A comment attribute would make it clear to the reader (or > automated documentation extraction program) who the comment > text is associated with while a stand-along XML comment is ambiguous. > > Merrill > > > > ------------------------------------------------------- This SF.Net email is sponsored by BEA Weblogic Workshop FREE Java Enterprise J2EE developer tools! Get your free copy of BEA WebLogic Workshop 8.1 today. http://ads.osdn.com/?ad_idP47&alloc_id808&op=click _______________________________________________ Nant-users mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/nant-users