Le migliori pratiche per contrassegnare il codice obsoleto in Ruby?

Vorrei contrassegnare un metodo come obsoleto, in modo che le persone che lo utilizzano possano facilmente controllare il proprio codice e recuperarlo. In Java hai impostato @Deprecated e tutti sanno cosa significa.

Quindi c'è un modo preferito (o persino strumenti) per contrassegnare e verificare le deprecazioni in Ruby?

Per quasi tutti i casi, dipendere da una libreria o metaprogrammazione per un deprezzamento è eccessivo. Basta aggiungere un commento a rdoc e chiamare il Kernel#warnmetodo. Per esempio:

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

Se stai usando Yard invece di rdoc , il tuo commento doc dovrebbe apparire così:

# @deprecated Please use {#useful} instead

Infine, se aderisci a tomdoc , fai in modo che il tuo commento assomigli a questo:

# Deprecated: Please use `useful` instead

Obsoleto: indica che il metodo è obsoleto e verrà rimosso in una versione futura. Dovresti utilizzarlo per documentare metodi che erano pubblici ma che verranno rimossi alla prossima versione principale.

Inoltre, non dimenticare di rimuovere il metodo obsoleto in alcune versioni future (e correttamente semver 'd) . Non commettere gli stessi errori delle librerie Java.

La Ruby Standard Library ha un modulo con la logica di avviso: https://ruby-doc.org/stdlib/libdoc/rubygems/rdoc/Gem/Deprecate.html . Tendo a preferirlo per mantenere i miei messaggi di deprecazione in modo "standard":

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

Nota che con questo approccio otterrai informazioni gratuite su dove è avvenuta la chiamata.

Se vuoi essere cattivo (con il pretesto di essere d'aiuto) puoi stampare la prima riga del callstack durante un avviso per far sapere agli sviluppatori dove stanno usando una chiamata deprecata.

Questo è cattivo perché sono abbastanza sicuro che sia un successo.

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

Se utilizzato correttamente, includerà il percorso assoluto del file e della linea in cui è stata utilizzata la chiamata obsoleta. Maggiori informazioni su Kernel :: caller sono disponibili qui

Utilizzando ActiveSupport:

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

Gli avvisi sono disattivati ​​nell'ambiente di produzione per impostazione predefinita

Puoi anche usare ActiveSupport::Deprecation(disponibile nella versione 4.0+), come tale:

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)

You have have libdeprecated-ruby(2010-2012, non più disponibile su rubygem nel 2015)

Una piccola libreria destinata ad aiutare gli sviluppatori che lavorano con codice deprecato.
L'idea viene dal ' D' linguaggio di programmazione, in cui gli sviluppatori possono contrassegnare un determinato codice come deprecato, quindi consentire / impedire la possibilità di eseguire codice deprecato.

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

Puoi usare il modello Class Mac e scrivere qualcosa del genere:

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

Quando si usano le rotaie, si ha il metodo deprecate Module #.

Canivete è un gioiello che ti consente di deprecare i tuoi metodi in modo semplice ed elegante. Un po 'di più qui .

Ho finito per mettere insieme un metodo leggero:

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

Quindi per deprecare un metodo inserire una chiamata nel corpo del metodo (o un costruttore per una classe)

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

È abbastanza dichiarativo e fornisce la registrazione con informazioni pertinenti. Non sono un gran rubino, quindi potrebbe essere necessario modificare / YMMV.

Possiamo usare metodi di macro interne. Esempio:

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) 

fine fine

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

o = Foo.new p o