Chapter 8. Comments

More is better! In particular, write comments for the intended use of properties and targets. The build file itself will tell what is happening, the comments should explain why.

For target comments, use a block comment similar to this example:

<!-- ==================== Dist Target ================================ 

    The "dist" target creates a binary distribution of the application
    in a directory structure ready to be archived in a tar.gz or zip file.
    This target depends on two others:

    * "compile" so that the entire web application (including external
      dependencies) will have been assembled

    * "javadoc" so that the application Javadocs will have been created

    ================================================================== -->

Place target comments immediately above the target element, with a single blank line between the end of the comment and the start of the target.

For other comments, such as for properties or within a target, use the standard xml single line comment like this:

<!-- this is a comment -->

If a comment is longer than a single line, wrap it and indent the second and subsequent lines 4 spaces, for example:

<!-- Put everything in ${build} into the MyProject-${DSTAMP}.jar file,
    then copy it and the source jar to the ${dist} directory so 
    everything will be ready for moving to the ftp server. -->

Do not put a blank line between a single line comment and the element it is describing, for example:

    <!-- this is where the api documents live -->
    <property name="api_docs" value="${docs_home}/api"/>