Лучшая практика помечать устаревший код в Ruby?

Question

Я бы хотел отметить метод как устаревший, чтобы люди, использующие его, могли легко проверить свой код и наверстать упущенное. В Java вы устанавливаете @Deprecated, и все знают, что это значит.

Так есть ли предпочтительный способ (или даже инструменты) для пометки и проверки на износ в Ruby?

Answer 1

Почти во всех случаях, в зависимости от библиотеки или метапрограммирования для устаревания является излишним. Просто добавьте комментарий к rdoc и вызовите метод Kernel#warn. Например:

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

---

Если вы используете Двор вместо rdoc , ваш комментарий к документу должен выглядеть следующим образом:

# @deprecated Please use {#useful} instead

Наконец, если вы придерживаетесь tomdoc , сделайте так, чтобы ваш комментарий выглядел следующим образом:

# Deprecated: Please use `useful` instead

Устаревший: указывает на то, что метод устарел и будет удален в следующей версии. Вы ДОЛЖНЫ использовать это для документирования методов, которые были Public, но будут удалены в следующей основной версии.

---

Кроме того, не забудьте удалить устаревший метод в будущем (и, соответственно, semver 'd) выпуск . Не допускайте тех же ошибок, что и библиотеки Java.

Answer 2

В стандартной библиотеке Ruby есть модуль с логикой предупреждения: http://ruby -doc.org / stdlib-1.9.3 / libdoc / rubygems / rdoc / Gem / Deprecate.html . Я предпочитаю, чтобы он поддерживал мои сообщения об устаревании "стандартным" способом:

# 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.

Обратите внимание, что при таком подходе вы получите бесплатную информацию о том, где произошел звонок.

Answer 3

Если вы хотите иметь в виду (под лозунгом полезности), вы можете распечатать первую строку callstack во время предупреждения, чтобы сообщить разработчикам, где они используют устаревший вызов.

Это значит, что Я почти уверен, что это удар по производительности.

warn Kernel.caller.first + " whatever deprecation message here"

При правильном использовании это будет включать абсолютный путь к файлу и строку, где использовался устаревший вызов. Больше информации о Kernel :: caller доступно здесь

Answer 4

Использование ActiveSupport:

class Player < ActiveRecord::Base
  def to_s
    ActiveSupport::Deprecation.warn('Use presenter instead')
    partner_uid
  end
end

По умолчанию предупреждения отключены в производственной среде

Answer 5

Вы также можете использовать ActiveSupport::Deprecation (доступно в версии 4.0+), например:

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)

Answer 6

У вас есть libdeprecated-ruby (2010-2012, больше не доступно на rubygem в 2015)

Небольшая библиотека, предназначенная для помощи разработчикам, работающим с устаревшим кодом.
Идея исходит из языка программирования D, где разработчики могут пометить определенный код как устаревший, а затем разрешить / запретить возможность выполнения устаревшего кода.

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

Answer 7

При использовании рельсов у вас есть метод Module # deprecate.

Answer 8

Вы можете использовать шаблон Class Macros и написать что-то вроде этого:

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

Answer 9

Я закончил тем, что бросил вместе легкий метод:

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

Затем для исключения метода вставьте вызов в тело метода (или конструктор для класса)

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

Это довольно декларативно и обеспечивает ведение журнала с соответствующей информацией. Я не очень разбираюсь в Rubyist, так что, возможно, потребуется немного подправить / YMMV.

Answer 10

Canivete - это драгоценный камень, который позволяет вам отказаться от ваших методов простым и элегантным способом. Еще немного об этом здесь .