Best practice to mark deprecated code in Ruby?
Solution 1:
For almost all cases, depending on a library or metaprogramming for a deprecation is overkill. Just add a comment to the rdoc and call the Kernel#warn
method. For example:
class Foo
# <b>DEPRECATED:</b> Please use <tt>useful</tt> instead.
def useless
warn "[DEPRECATION] `useless` is deprecated. Please use `useful` instead."
useful
end
def useful
# ...
end
end
If you're using Yard instead of rdoc, your doc comment should look like this:
# @deprecated Please use {#useful} instead
Lastly, if you adhere to tomdoc, make your comment look like this:
# Deprecated: Please use `useful` instead
Deprecated: Indicates that the method is deprecated and will be removed in a future version. You SHOULD use this to document methods that were Public but will be removed at the next major version.
Also, don't forget to remove the deprecated method in some future (and properly semver'd) release. Don't make the same mistakes that the Java libraries did.
Solution 2:
Ruby Standard Library has a module with the warning logic: https://ruby-doc.org/stdlib/libdoc/rubygems/rdoc/Gem/Deprecate.html. I tend to prefer it to maintain my deprecation messages in a "standard" way:
# my_file.rb
class MyFile
extend Gem::Deprecate
def no_more
close
end
deprecate :no_more, :close, 2015, 5
def close
# new logic here
end
end
MyFile.new.no_more
# => NOTE: MyFile#no_more is deprecated; use close instead. It will be removed on or after 2015-05-01.
# => MyFile#no_more called from my_file.rb:16.
Note that with this approach you will gain for free information about where the call took place.
Solution 3:
Using ActiveSupport:
class Player < ActiveRecord::Base
def to_s
ActiveSupport::Deprecation.warn('Use presenter instead')
partner_uid
end
end
Warnings are turned off in production environment by default
Solution 4:
If you want to be mean (under the guile of being helpful) you can print out the first line of the callstack during a warning to let devs know where they are using a deprecated call.
This is mean because I'm pretty sure it's a performance-hit.
warn Kernel.caller.first + " whatever deprecation message here"
When used correctly, this will include the absolute path to the file and line where the deprecated call was used. More information about Kernel::caller is available here