Task tracking numbers are not a substitute for documentation
Do you think this is an appropriate and sufficient documentation for this function?
# 3978
#
sub is_contact_in_abook_for_user {
This number refers to the task number in a task/bug tracking system. The idea being, why write documentation, when that would simply duplicate what is already available.
There are a number of reasons why this sort of documentation is bad, but the main one is that a feature lives on a for a long time, as does reusable code which one creates in order to implement the particular feature. But a task is just a task, once it's done, no one cares about it any more. So if one sees e.g. a class modelling a user exposing methods such "fetch by user name", "fetch by id", "fetch by telephone number", it isn't really helpful to know that the first two were implemented as part of a "implement payment" feature, and the last for a "mobile phone shop" feature. There are so many aspects of those features which have nothing to do with a function which can be reused time and time again.
The other reasons are:
- You cannot click "3978" and see the documentation. You have to open a browser window, search for the task, and so on. This is a lot of work, so many people will never do it, meaning they'll alter the code without understanding what it's doing. This may be their fault, as opposed to the fault of the process, but it's a reality nevertheless.
- What about the other documentation for the function? What are the return types? What are the parameter types? It's not documented here and I bet it's not documented as a "comment" to task #3978.
- Task trackers get changed over the life of the program. In this case, the original task tracker was maintained by another company with whom my customer no longer has a relationship. So I have no way whatsoever to find anything about task #3978 or any other. So all those comments littered throughout the program are literally useless.
I think the solution is the task tracker should reference the code, not the other way around. E.g. a comment by a programmer "adrian 20th dec 2006: committed file MyClass.java in svn revision 2938".