Xzajo's Weblog

Friday April 14, 2006

The best documentation of API - unit test

Developers don't like writing of documentation. Many tutorials and documentations are obsolete. I saw wrong javadoc comments sometimes. I claim that the best documentation of API are the unit tests.

• The unit test cannot be obsolete if is run daily.
• The unit test is tutorial of the tested code.
• It contains recommended design patterns.
• The code will be more reliable if already tested patterns are used.

For example I was reading javadoc of Java Language Model API (JMI). From the javadoc I didn't get knowledge how to read, create and modify annotations. Thanks to Google I found some unit tests of JMI module which uses annotations. I can use a pattern shown bellow in my code and I'm sure that it is good usage.

 public void testAddAnnotation() throws java.io.IOException, FileStateInvalidException {
        boolean fail = true;
        Utility.beginTrans(true);
        try {
            Method method = (Method) clazz.getContents().get(0);
            // log the annotation information
            getLog().println("Method '" + method.getName() + "' has following annotations:");
            for (Iterator it = method.getAnnotations().iterator(); it.hasNext(); ) {
                Annotation annotation = (Annotation) it.next();
                getLog().println("\tAnnotation named '" + annotation.getType().getName() + "'.");
                for (Iterator it2 = annotation.getAttributeValues().iterator(); it2.hasNext(); ) {
                    AttributeValue attribute = (AttributeValue) it2.next();
                    getLog().println("\t\tAttribute value '" + attribute.getName() + "', '" + ((MetadataElement) attribute.getValue()).getSourceText() + "'.");
                }
            }
            Annotation ann = createSimpleAnn("\"2004-06-21\"", "\"Lojza\"", "\"Unknown\"", "46");
            method = (Method) clazz.getContents().get(1);
            method.getAnnotations().add(ann);
            fail = false;
       }
        finally {
            Utility.endTrans(fail);
        }
        assertFile("File is not correctly generated.",
            Utility.getFile(getDataDir(), "org/netbeans/test/codegen/AnnotationClass.java"),
            getGoldenFile("testAddAnnotation_AnnotationClass.pass"),
            getWorkDir()
        );
    }

I got a idea. Why not to add link to unit tests to javadoc html. TestNG uses annotations to specify tests groups. Why to not add annotations which package, class or method is tested. The link to test sources should be added to javadoc documentation. The test can be also indexed. Usage statistics can shown in javadoc. After that many developers, who don't write tests, will have to write tests I hope. Because the API users (developers) rather choose already tested API.