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] Universal Package Manager - ProGet easily integrates with your favorite Continuous Integration and Build Tools, acting as the central hub to all your essential components. Learn more today!
To read the full article, please visit The Daily WTF
No comments:
Post a Comment