Commenting code

I have found extremely valuable to follow basic documenting standards like the ones described in this article

I've written some code that can retrieve the complete JS source file from the server and generate the API documentation, which allows us to keep our served files lean (the comments are removed before serving them to the client, hence "complete") and to enforce good documentation (since people reusing the code have only access to the API).

This level of separation keeps people reusing our code happy because it's easy to figure out how to use and at the same time it ensures that the documentation is complete and accurate -- no one likes being interrupted because the documentation is incomplete.

No comments: