entropia

Programmers don’t like writing documentation; documentation is important; most documentation is bad.  Blah, blah, blah, you’ve heard it all before.  There are plenty of tools that help you with documentation, mostly by automating it somehow.  I’ve tried a few, but none of them have helped at all.

I think the problem is not writing documentation so much as keeping up-to-date documentation.

Imagine you start writing a function that will foo all supplied bars and return foobars.  You put a comment at the top of the function to state this.  Then later you change the function to make it baz all bars in addition to fooing them.  And you forget to update the comment.

You now have incorrect documentation, which is worse than no documentation at all.

The solution is for the IDE to keep track of when each comment¹ and each function was last updated.  If the function is newer than the comment, highlight the comment as old.  Add in a little reporting feature (list all functions with old comments), and the quality of documentation will improve.

Now it’s easy to see where the documentation suffers with nothing more than a glance.  This solves the problem by removing the requirement that the programmer actively keeps track of documentation and gives the task to the IDE.  It could also be extended to documentation written in, say, Word.  Tie each piece of the document to a function or file and use the same logic for finding the old stuff.

I haven’t seen this before, but I’d be surprised if no one has done it yet.

1. I’m referring to specifically function-level comments here — the kind Visual Studio puts in the summary tag — but this can be extended to other documentation. [↩]