Ant Best Practices: Provide good help
• Julian Simpson
This is the fourth post in my series of posts examining Eric M Burke's
Top 15 Ant Best Practices from December 2003. The last one I covered was 'Prefer a single buildfile'. Today's is 'Provide good help'. Eric starts by suggesting that you should make use of public targets to document the targets that you should be able to invoke.
Now, the distinction between a public and a private target in [N]Ant is pretty subtle: If the target has a descrption, it's public and will show up when you call Ant with the -p or the -projecthelp option. If a target has no description, it's private. So, the description attribute signifies that the target is for public consumption; and also has the side effect of telling you what you can do with it. Using this mechanism is a no-brainer - but how do you protect a private, or internal target? There's no way that you can declare a target as private, but you can stop the target from being called from the command line by prefixing it with a hyphen.
For example, if you have a target called start-weblogic that you don't want called from the command line, you can call it -start-weblogic. If you try and invoke it, look what happens:
graham-tackleys-mac-mini:~ jsimpson$ ant -start-weblogic
Unknown argument: -start-weblogic
ant [options] [target [target2 [target3] ...]]
Options:
-help, -h print this message
-projecthelp, -p print project help information
-version print the version information and exit
Eric also suggests 2 other things: using XML comments to provide more detail, and making a help target that echoes out some useful help messages. I don't think I'd ever disagree with a help target. I might disagree about the XML comments. Generally I use XML comments as temporary notes to myself. It's nicer to use the description attribute on elements in build.xml files: just about every element will accept one, and you can make sure that the text always matches the element.
<project name="MyGreatProject" default="test">
<property environment="env" />
<property file="override.properties" description="this gets all the special properties"/>
So far, that's about 4 out of 4 practices that have held up. Next: clean targets.