Comments

comments.py

# This is not good because it's unclear
if elapsed_seconds > 86400:
    return 'expired'

# While less opaque the comment is a crutch to 
# get around the unclear code
if elapsed_seconds > 86400:  # seconds in a day
    return 'expired'

# This is better, but still not great. It necessitates
# cluttering up namespace and while it improves readability
# in the conditional 86400 could still be checked by the
# reviewer
seconds_per_day > 86400
if elapsed_seconds > seconds_per_day:
    return 'expired'

# This shows immediately obvious intention and is easy
# for the reviewer to evaluate the correctness of it.
# However, it's still going to create a maintenance
# burden if we ever want to change our expiry time
# and it's referenced anywhere else.
if elapsed_seconds > 60 * 60 * 24:
    return 'expired'

# This is much better. No comment needed when the unit
# conversion is performed and shows seperation of concerns
# between the date math and the actual expiry business 
# logic.
cache_expiry_seconds = 60 * 60 * 24
if elapsed_seconds > cache_expiry_seconds:
    return 'expired'

# As much as I'd like to expect most programmers to just 
# recognize 86400 just like I'd expect a chemist to 
# recognize 22.4, I don't think it's a great practice to
# rely on.