Найкраща практика позначення застарілого коду в Ruby?

Я хотів би позначити метод як застарілий, тому люди, які використовують його, можуть легко перевірити свій код і наздогнати його. На Java ви встановлюєте @Deprecated, і всі знають, що це означає.

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

Майже у всіх випадках залежно від бібліотеки чи метапрограмування депрекація є надмірною. Просто додайте коментар до 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

Якщо ви використовуєте Yard замість rdoc , коментар до документа повинен виглядати так:

# @deprecated Please use {#useful} instead

І нарешті, якщо ви дотримуєтеся Tomdoc , зробіть ваш коментар таким чином:

# Deprecated: Please use `useful` instead

Застаріле: Позначає, що метод застарілий і буде видалений у наступній версії. Ви повинні використовувати це для документування методів, які були загальнодоступними, але будуть видалені в наступній основній версії.

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

Стандартна бібліотека Ruby має модуль з логікою попередження: https://ruby-doc.org/stdlib/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.

Зауважте, що при такому підході ви отримаєте безкоштовну інформацію про те, де відбувся дзвінок.

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

Це означає, тому що я майже впевнений, що це хіт на виставу.

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

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

Використання ActiveSupport:

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

Попередження вимикаються у виробничих умовах за замовчуванням

Ви також можете використовувати 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)

У вас є libdeprecated-ruby (2010-2012 рр., Більше не доступний на рубігемі у 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

Ви можете використовувати шаблон класу макросів і написати щось подібне:

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

Під час використання рейок у вас є метод знеструмлення модуля #.

Canivete - це дорогоцінний камінь, який дає змогу просто і елегантно знестирити свої методи. Трохи більше про це тут .

Я закінчила співати легкий метод:

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

Це досить декларативно і забезпечує ведення журналу з відповідною інформацією. Я не сильно рубіст, тому це може знадобитися певного налаштування / YMMV.

Ми можемо використовувати внутрішні методи макросів. Приклад:

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) 

кінцевий кінець

deprecate: a,: get_a deprecate: b,: get_b deprecate: c,: get_c кінець

o = Foo.новий p oa