Meilleures pratiques pour marquer le code obsolète dans Ruby ?

Question

Je tiens à marquer une méthode comme obsolète, donc les personnes qui l’utilisent peuvent facilement vérifier leur code et rattraper son retard. En Java, vous définissez @Deprecated et tout le monde sait ce que cela signifie.

Alors y a-t-il un meilleur moyen (ou même outils) pour marquer et recherchez les désapprobations dans Ruby ?

Answer 1

Pour presque tous les cas, en fonction d'une bibliothèque ou de la métaprogrammation par une dépréciation est exagéré. Il suffit d'ajouter un commentaire pour la rdoc et d'appeler l' Kernel#warn méthode. Par exemple:

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

---

Si vous utilisez la Cour au lieu de rdoc, votre doc commentaire devrait ressembler à ceci:

# @deprecated Please use {#useful} instead

Enfin, si vous adhérez à tomdoc, faire votre commentaire ressemble à ceci:

# Deprecated: Please use `useful` instead

Obsolète: Indique que la méthode est obsolète et sera supprimée dans une future version. Vous DEVRIEZ l'utiliser pour documenter les méthodes qui ont été Public, mais seront supprimés à la prochaine version majeure.

---

Aussi, n'oubliez pas de retirer la méthode dépréciée dans l'avenir (et correctement semver'd de presse). Ne faites pas les mêmes erreurs que les bibliothèques Java n'.

Answer 2

Ruby Library Standard dispose d’un module avec la logique de mise en garde : http://ruby-doc.org/stdlib-1.9.3/libdoc/rubygems/rdoc/Gem/Deprecate.html. J’ai tendance à préférer à conserver mes messages de désapprobation d’une façon « standard » :

Notez que cette approche vous permettra d’avoir gratuitement informations sur où l’appel a eu lieu.

Answer 3

Si vous voulez être en moyenne (en vertu de la ruse d'être utile) vous pouvez imprimer la première ligne de la pile des appels lors d'un avertissement de laisser les devs savent où ils sont à l'aide d'un type d'appel obsolète.

C'est dire parce que je suis sûr que c'est une performance-hit.

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

Lorsqu'il est utilisé correctement, cette comprendra le chemin absolu vers le fichier et la ligne où le obsolète appel a été utilisé. Plus d'informations sur le Noyau::l'appelant est disponible ici

Answer 4

Vous pouvez également utiliser `` (disponible en version 4.0 +), comme tel :

Answer 5

Vous avez libdeprecated-ruby (également sur rubygems)

Une petite bibliothèque destinée à aider les développeurs qui travaillent avec code obsolète.
L'idée vient de la 'D' langage de programmation, où les développeurs peuvent marquer un code comme obsolète, et ensuite autoriser/interdire la possibilité d'exécuter du code obsolète.

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