- Assumptions that the routine makes (e.g. a resource is locked by the caller before the routine is called; the routine isn't called very often so performance is not important and the implementation is simplified). Obviosly, you'll want to put in assertion-like sanity checks to handle these whenever you can, but there are cases where this is not possible and these may be buried (hence obfuscated) in the code.

- Limitations of the implementation and future changes that could be made. Many times this is something like an idea of how to improve performance (i.e. by introducing some complexity) if an assumption changes about how the routine will be used in the future.

Unfortunately, some project management types who believe that "more == better" get real pedantic and start mandating that all sorts of useless drivel appear here that is either quickly outdated and/or can be gleaned from the first two lines of the sub.

bluto