Name: rmT116609 Date: 01/17/2001


java -version 1.3

It's only been in the last year or two that Java performance is starting to get
some serious attention. By this I don't mean speed of the JVM, but rather speed
of Java applications. I suspect this will be even more of an issue as J2ME
usage increases on small processor devices.

Unfortunately, most developers don't document performance. Most software
contains only high level performance information, often in the form of
benchmarks. What is not included are comments about the performance (speed and
memory usage) of particular subsystems, classes, and even methods. I am
currently trying to get my developers to also comment on these issues in their
javaodcs. Information of this nature is useful to both users of 3rd party APIs,
as well as internally, to development teams, as they continually reuse,
refactor, and improve their code.

I have found Javadoc to be very useful in getting my developers to get into good
documentation habits. The tags, especially, help guide them as to what
information to include. (Thanks for the javadoc tool, btw.) What I would like
to propose is some type of support for documenting performance. However it is
implemented, it should probably be done so in a way that can be easily
optionally included/removed, as some API developers may wish to record the
information, but not release it. I realize that with today's javadoc we can
create our own tags and can implement this functionality on our own. I plan to
do that. But it would be nice to see this information included in the javadoc
tool for two reasons. First, it would be standardized. Second, it would help
to encourage developers to consider performance, and include performance
documentation.
(Review ID: 115327)
======================================================================