[bcl]

The problem with doing it that way is that someone who comes across a checkout of your code will have no documentation. Think about the case of a distributed tar.bz2 or having a python application installed on your system.

I prefer to have the comments in the code, in a form that can be used to generate documentation on the side (eg. doxygen, epydoc, etc.) so that they can't get lost, and so that you can read them as you read the code. It is difficult to re-combine the git commit messages with the code, but not hard to extract the comments from the code to create documentation.