Comments are rough. I always take the stance that code should always be clear enough to explain what it does, but youll may need a comment to explain why it does that. I recently attended a talk by Sean Griffin (maintainer of Rails) who argued that commit messages should accomplish that goal, since they can contain far more content than a code comment, and while code comments and code can drift apart and cease to be accurate, commit messages are always linked to the point-in-time when they were made. Donald Knuth, on the other hand, might argue that code should annotate comments instead of the opposite.

Regardless of the method we use, I think most of us would agree that code needs some documentation in the same way it needs tests: it should exist, but we dont want to have to create it.

Stephania found herself in the situation where she was creating the documentation. In this case, I dont think we have to worry about the comment ceasing to be an accurate description of the code. This comment doesnt need to be linked to a specific point in time- it tells us everything we need to know about the entire codebase.

# Note: The parameters "backup_freq" below do not actually refer to how frequently the backup script runs.  
# It's just a tag so that the retention scripts know what kind of backup the created snapshot is.
# How often the script runs is determined by the name of the generated output file.

http://thedailywtf.com/articles/accuracy-in-comments