Accuracy in Comments

Comments are rough. I always take the stance that code should always be clear enough to explain what it does, but you’ll 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 don’t want to have to create it.

Stephania found herself in the situation where she was creating the documentation. In this case, I don’t think we have to worry about the comment ceasing to be an accurate description of the code. This comment doesn’t 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.

[Advertisement] BuildMaster allows you to create a self-service release management platform that allows different teams to manage their applications. Explore how!