153

I'd like to mark a method as deprecated, so the people using it can easily check their code and catch up. In Java you set @Deprecated and everybody knows what this means.

So is there a preferred way (or even tools) to mark and check for deprecations in Ruby?

2
  • To be fair, Java's annotation sucks, as it has no value to point to a potential replacement
    – Heiko Rupp
    Commented Nov 3, 2015 at 13:48
  • @HeikoRupp I know this is 8 years late, but this sort of comment isn't really helpful. Commented Feb 15, 2023 at 14:02

11 Answers 11

185

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.

4
  • 5
    I am not sure it is so much a "mistake" from the Java part, rather a huge backward compatibility issue (see stackoverflow.com/questions/314540), that blindgaenger might not need to consider for his Ruby code.
    – VonC
    Commented Dec 31, 2008 at 20:46
  • 46
    Code is a liability. The less code you have to maintain the better. Deprecations are good for temporary backwards compatibility, but over time it becomes cruft. If people need to use retired methods, they should use older versions of your libraries instead. Commented Dec 31, 2008 at 21:22
  • 3
    Excelent response. I just want add a link to the response where I show the approach that I've used lately, which relies on the Ruby Std Lib: stackoverflow.com/questions/293981/… Commented May 10, 2014 at 14:19
  • 2
    @RicardoValeriano I agree, your response should be integrated (or higher voted, or both :) ).
    – Felix
    Commented Oct 25, 2016 at 6:17
79

Ruby Standard Library has a module with the warning logic: https://ruby-doc.org/core-3.1.2/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.

6
  • Nice, didn't know about this in standard lib.
    – Kris
    Commented Mar 29, 2016 at 11:33
  • 2
    the leading 0 for a numeric literal makes it octal and so should likely be removed. Commented Jun 8, 2016 at 15:29
  • 7
    Thanks for the tip. I deprecated an entire class, and suggested the newer class to be used: deprecate :initialize, UseThisClassInstead, 2017, 5
    – Jon Kern
    Commented Feb 12, 2017 at 22:56
  • Great usage example, Jon. Really nice one. Commented Feb 13, 2017 at 9:59
  • 10
    The previous correct answer has been deprecated and the answer by Ricardo Valueriano should now be used
    – simon
    Commented Mar 2, 2017 at 13:37
22

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.

14

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

1
  • 5
    I don't consider this mean. A small performance hit is nicer than having to chase down where the deprecated call was, and much nicer than something breaking when the method is eventually removed. Commented Dec 10, 2012 at 18:41
14

You can also use ActiveSupport::Deprecation (available in version 4.0+), as such:

require 'active_support/deprecation'
require 'active_support/core_ext/module/deprecation'

class MyGem
  def self.deprecator
    ActiveSupport::Deprecation.new('2.0', 'MyGem')
  end

  def old_method
  end

  def new_method
  end

  deprecate old_method: :new_method, deprecator: deprecator
end

MyGem.new.old_method
# => DEPRECATION WARNING: old_method is deprecated and will be removed from MyGem 2.0 (use new_method instead). (called from <main> at file.rb:18)
8

You do have libdeprecated-ruby (2010-2012, not available anymore on rubygem in 2015)

A small library intended to aid developers working with deprecated code.
The idea comes from the 'D' programming language, where developers can mark certain code as deprecated, and then allow/disallow the ability to execute deprecated code.

require 'lib/deprecated.rb'
require 'test/unit'

# this class is used to test the deprecate functionality
class DummyClass
  def monkey
    return true
  end

  deprecate :monkey
end

# we want exceptions for testing here.
Deprecate.set_action(:throw)

class DeprecateTest < Test::Unit::TestCase
  def test_set_action

    assert_raise(DeprecatedError) { raise StandardError.new unless DummyClass.new.monkey }

    Deprecate.set_action(proc { |msg| raise DeprecatedError.new("#{msg} is deprecated.") })

    assert_raise(DeprecatedError) { raise StandardError.new unless DummyClass.new.monkey }


    # set to warn and make sure our return values are getting through.
    Deprecate.set_action(:warn)

    assert_nothing_raised(DeprecatedError) { raise StandardError.new unless DummyClass.new.monkey } 
  end
end
1
3

You can use Class Macros pattern and write something like this:

class Module     
     def deprecate(old_method, new_method)
          define_method(old_method) do |*args, &block|
               warn "Method #{old_method}() depricated. Use #{new_method}() instead"
               send(new_method, *args, &block)
          end
     end
end


class Test
     def my_new_method
          p "My method"
     end

     deprecate :my_old_method, :my_method
end
3

When using rails, you have the Module#deprecate method.

2

Canivete is a gem which enables you to deprecate your methods in simple and elegant way. A little more about it here.

1

I ended up throwing together a lightweight method:

def deprecate(msg)
  method = caller_locations(1, 1).first.label
  source = caller(2, 1).first
  warn "#{method} is deprecated: #{msg}\ncalled at #{source}"
end

Then to deprecate a method insert a call in the method body (or a constructor for a class)

def foo
  deprecate 'prefer bar, will be removed in version 3'
  ...
end

It's fairly declarative and provides logging with relevant info. I'm not much of a Rubyist so it may need some tweaking/YMMV.

0

We can use internal macros methods. Example:

class Foo def get_a; puts "I'm an A" end def get_b; puts "I'm an B" end def get_c; puts "I'm an C" end

def self.deprecate(old_method, new_method)
  define_method(old_method) do |*args, &block|
     puts "Warning: #{old_method} is deprecated! Use #{new_method} instead"
     send(new_method, *args, &block) 

end end

deprecate :a, :get_a deprecate :b, :get_b deprecate :c, :get_c end

o = Foo.new p o.a

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.