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

Reply via email to