Best practices for deprecating functions

user_13693623 0
Viewed 82

Does anyone have any clever ways to signal a function is deprecated? I've thought of:

  • Removing the symbol from package exports
  • Emitting warning suggesting the new API be used

I'm not terribly fond of either. One breaks code and the other clutters output. I do want people to stop using the old functions, and have found declaring them deprecated in the documentation and then removing them at some point in the future rarely works well; people are still 'surprised' when they get removed.

Anyone have any good ideas in this area?

common-lisp
1 Answers

The best bet is usually to emit warnings at compile time:

(defvar *deprecation-warnings* t)

(defvar *deprecation-locations*
  (make-hash-table :test #'equal))

(defmacro define-deprecated-function (f args &body forms)
  `(progn
     (defun ,f ,args ,@forms)
     (define-compiler-macro ,f (&whole form &rest args)
       (declare (ignore args))
       (when *deprecation-warnings*
         (warn "Deprecated function ~S~@[ in ~A~]"
               ',f *compile-file-truename*))
       (when *compile-file-pathname*
         (pushnew *compile-file-truename*
                  (gethash ',f *deprecation-locations*)
                  :test #'equal))
       form)))

(defun report-deprecations (&key (clear nil) (stream t))
  (maphash (lambda (f locations)
             (format stream "~&~S ~{~A~^, ~}~%" f locations))
           *deprecation-locations*)
  (when clear
    (clrhash *deprecation-locations*))
  (values))

With similar things for other sorts of thing (generic functions etc).

Then you can, say

(define-deprecated-function foo (...)
  ...)

And all code that calls foo will now get a warning at compile time. report-deprecations will tell people what things are deprecated and where.

Of course, people will still ignore the warnings and then whine fiercely when the deprecated functionality goes away. There is no solution for that problem.

[I never know whether I should write 'deprecation' or 'depreciation' here...]

user_170269340
Related