Comment Drift

bad_comment.rb

# This methods adds 2 numbers together
# @param x [Number] The first number that you would 
#                   like to add
# @param y [Number] The number you would 
#                   like to add to the first number
# @return [Number] The result of adding `x` and `y` together
def add(x, y)
  x + y
end

better_comment.rb

# Adding 2 numbers together is a pretty important action 
# for the system. We’ve chosen the traditional interpretation 
# of what it means to "add."
#
# We were under some time pressure at the time, so we 
# realize that this is not the most optimized implementation.
#
# If you need to ask someone about how or why this works
# the way it does, go talk to Kelly or someone else
# originally on Project X.
def add(x, y)
  x + y
end