The line between code and documentation is blurring with the introduction of regimented documentation standards. In PHP reflection (and likely other languages as well) you can use reflection to programmatically access documentation blocks meaning you *could* make code dependant on information in your doc comments! Scary!

More scary is that I discovered this via a colleague who was considering using this. You could argue it conforms to the DRY principle because we were looking to add more strict control of return types implemented in methods that are derived from an interface we defined. This would require us to redefine information already part of our doc comments should we proceed without the reflection API.

For now we have elected not to proceed because it violates the rule of least surprise. Developers do not expect edits to comments affecting code conditionals and thus our effort to enforce correct use of interfaces could backfire causing exceptions in classes implementing our defined interfaces.

At some later date when the trend has continued and there is no line between code and API documentation or at such point we are confident our unit testing will prevent deployment of exceptions due to incorrect documentation we may reconsider this approach.

Stumble it!