Clean Code

In his book Clean Code Robert C. Martin dedicated one chapter with over 20 pages on comments. Needless to say that this chapter is very worth reading.

Effective Java

Joshua Bloch has some items in his book Effective Java dealing with writing API documentation.

• Item 17: Design and document for inheritance or else prohibit it
• Item 44: Write doc comments for all exposed API elements
• Item 62: Document all exceptions thrown be each method
• Item 70: Document thread safety
• Item 75: Consider using a custom serialized form

Patterns kompakt

This is a pocket book on patterns but gives the authors' opinion on API documentation of small methods. Therefore we cite the German book Patterns kompakt by Karl Eilebrecht and Gernot Starke. The documentation relevant section is found on pages 12 to 14, titled Grundprinzipien der Dokumentation (basic principles of documentation).

Practical API Design

Jaroslav Tulach has some interesting points in his book Practical API Design.

If the development of a modular application is to be successful and effective, a clear understood, well-documented, and as far as possible, self-documented API is needed. [...] The API needs to be self-documenting: in other words, usable without any documentation. (p. 23f)

The better the documentation, the less effort is needed to understand and use the library. That is why having a good documentation is a must for every successful framework. (p. 294)

When coding in the IDE and using code completion, wouldn't it be useful to jump from there straight to a tutorial related to the usage of the current method? Indeed it would be, and the only required task is to enhance the Javadoc method with pointers to the related tutorial. (p. 295f)