Bob Lee's Blog - Java and some occasional baby making
Pages
▼
Monday, May 01, 2006
Code Examples in Javadocs
I wish IntelliJ provided some basic syntax highlighting, completion, and formatting for code examples in Javadocs. What a pain. I'll bet more developers would write them if it did.
Another good idea is to write good code examples in the programmer tests of your component. When figuring out what a component is doing, it's always a good idea to search for its references in the code base, and when tests are found, check them out (though this is not easy to do if you're working with a library without its source code in your IDE.)
If compelled, you can then copy the code from the tests over to the javadocs. But the code in javadocs has the disadvantage of lacking compile- and run-time checking, so it gets out of date more easily than the executable examples in tests.
Anyway, thankyou for raising a good point. I think that I'll consider adding a '@see FooTest' to my code sometimes.
You can still get ctl-shift completion within Javadoc.
ReplyDeleteYou should vote for Add code completion in {@code} javadoc tag
ReplyDeleteAnother good idea is to write good code examples in the programmer tests of your component. When figuring out what a component is doing, it's always a good idea to search for its references in the code base, and when tests are found, check them out (though this is not easy to do if you're working with a library without its source code in your IDE.)
ReplyDeleteIf compelled, you can then copy the code from the tests over to the javadocs. But the code in javadocs has the disadvantage of lacking compile- and run-time checking, so it gets out of date more easily than the executable examples in tests.
Anyway, thankyou for raising a good point. I think that I'll consider adding a '@see FooTest' to my code sometimes.
Java continues to be evil!
ReplyDelete** Shaun **
My awesome blog: ohpunk.blogspot.com
-