This article on painting
http://java.sun.com/products/jfc/tsc/articles/painting/index.html
should mention that it is a poor idea to change the GUI hierarchy in the
paint() or update() method of a component. Perhaps we could put it in the
AWT Painting Guidelines section? Below is some sample text.

Changing the state of the GUI (e.g. adding an item to a List, or calling the
setBackground() method of a Component) in the paint() or update() method of a
Component is discouraged. These operations typically result in a new paint
event being posted, so doing them in the paint() or update() method may
cause a loop in which the paint method is called repeatedly.

This may seem like an obvious error, but we have found several examples where
programmers do this. Perhaps it is worth mentioning in the tutorial or some
other docs.