Ansätze zur Deklaration von Code als veraltet in JavaScript

Vor kurzem musste ich mich mit dem Thema der Code-Deklaration als veraltet in JavaScript auseinandersetzen. Ich habe das Gefühl, dass diesem Thema weniger Beachtung geschenkt wird, obwohl es in bestimmten Projekten eine Schlüsselrolle spielen kann, insbesondere bei der Arbeit in größeren Teams oder beim Umgang mit externen APIs.

In der JavaScript-Welt kenne ich keine wirklichen Industriestandards für die Deklaration von JavaScript als veraltet. Das kann je nach Team, Bibliothek oder Anbieter unterschiedlich sein.

Deshalb ist es mein Ziel hier, meine Erkenntnisse und Gedanken zu diesem Thema zusammenzufassen, zusammen mit einigen bewährten Praktiken, wenn es darum geht, eine JavaScript-Methode als veraltet zu kennzeichnen.

Was bedeutet "Veraltung" eigentlich?

Zunächst einmal sei klargestellt, dass die Veraltung nur ein Status ist, der auf ein Software-Feature angewendet wird. Sie zeigt an, dass dieses Feature vermieden werden sollte, in der Regel, weil es ersetzt wurde.

Veraltung kann auch bedeuten, dass das Feature in Zukunft entfernt wird. Features werden veraltet – anstatt sofort entfernt zu werden –, um die Abwärtskompatibilität zu gewährleisten und Programmierern, die das Feature verwendet haben, Zeit zu geben, ihren Code an den neuen Standard anzupassen.

Darüber hinaus deutet ein veraltetes Feature darauf hin, dass es von diesem Zeitpunkt an keine weitere Entwicklung mehr geben wird. Es sollte sich nicht anders verhalten als in einer früheren Version (es sei denn, die Dokumentation gibt ausdrücklich etwas anderes an). Im Allgemeinen sollte es also dasselbe sein wie zum Zeitpunkt der Veraltung.

Es kann in der neuesten Version funktionieren oder auch nicht – keine Garantie!

Da es in der JavaScript-Welt jedoch keine wirklichen Industriestandards gibt, die strikt befolgt werden, kann dies je nach Team, Bibliothek oder Anbieter leicht variieren.

Wann Code veraltet deklarieren und wann löschen?

Es ist wichtig zu beachten, dass ein veraltetes Software-Feature oder eine veraltete Methode immer noch Teil der Software ist! Betrachten Sie das Label "veraltet" als reinen Status des Codes. Ob das Software-Feature tatsächlich in Zukunft entfernt wird, hängt von der Entscheidung des jeweiligen Software-Teams ab.

Meiner Meinung nach sollten große Teams oder Projekte, die von externen APIs oder Bibliotheken abhängig sind, zuerst veraltet deklarieren und dann später entfernen (nach angemessener Zeit, wie auch immer Sie das definieren). Geben Sie zumindest mindestens einen Hauptversionssprung an, bevor Sie den veralteten Code tatsächlich entfernen, damit die Benutzer die Möglichkeit haben, sich an die Änderung anzupassen.

Vielleicht möchten Sie sich mit Semantic Versioning befassen, einer einfachen Reihe von Regeln und Anforderungen, die vorgeben, wie Versionsnummern zugewiesen und inkrementiert werden. Bei einer Versionsnummer MAJOR.MINOR.PATCH inkrementieren Sie die MAJOR-Version, wenn Sie inkompatible API-Änderungen vornehmen, die MINOR-Version, wenn Sie Funktionalität auf abwärtskompatible Weise hinzufügen, und die PATCH-Version, wenn Sie abwärtskompatible Fehlerbehebungen vornehmen.

Wenn Ihre Software sich schnell ändert und weiterentwickelt und Sie ein Feature veraltet deklarieren, versuchen Sie, mit Ihrem Projektmanager zu kommunizieren, ob dieses Feature voraussichtlich später wiederbelebt wird. Wenn Sie sich entscheiden, etwas zu veralten anstatt zu löschen, kann es für Sie viel einfacher sein, es rückgängig zu machen, falls Sie es benötigen.

Für kleinere Teams oder Projekte mit internen Methoden und APIs können Sie ruhig zuerst löschen, anstatt zu veralten. Manchmal macht es einfach keinen Sinn, Zeit zu verschwenden, und die Veraltung erhöht nur die Komplexität, nur um Best Practices zu folgen.

Wie kennzeichnet man eine Methode als veraltet

Hier sind fünf bewährte Praktiken, die ich am nützlichsten gefunden habe

1. Fügen Sie ein @deprecated JSDoc-Flag hinzu.
2. Erwähnen Sie die Version, in der die Methode veraltet wurde.
3. Legen Sie einen Zeitrahmen fest, wann diese Methode gelöscht wird, einschließlich der Version, die sie ersetzen wird. Andernfalls bleibt sie meiner Erfahrung nach für immer 🙂
4. Verwenden Sie Kommentare großzügig, um die Implementierung zum Nutzen anderer Entwickler oder Ihres zukünftigen Selbst zu erklären. Dies ist äußerst nützlich, wenn Sie eine Bibliothek schreiben, die andere als Abhängigkeit für ihre Arbeit verwenden.
5. Fügen Sie eine Konsolenwarnmeldung hinzu, die darauf hinweist, dass die Funktion veraltet ist.

Hier ist ein praktischeres Beispiel, bei dem ich alle fünf Praktiken anwende

/**
 * A magic method that multiples digits.
 *
 * @deprecated [#1] since version 2.3 [#2].
 * [#3] Will be deleted in version 3.0.
 
 * [#4] In case you need similar behavior, implement it on you own,
 * preferably in vanilla JavaScript
 * or use the multiplyTheSameNumber method instead,
 * if the same number needs to be multiplied multiple times, like so:
 * multiplyDigits([5, 5, 5]) === multiplyTheSameNumber(5, 3)
 *
 * @param {array} _digits - digits to multiply
 */
function multiplyDigits(_digits) {
  console.warn("Calling a depricated method!"); // [#5]
  
  // ....
}

Um Wiederholungen in den Konsolenwarnungen zu vermeiden oder falls Sie mehrere Methoden veraltet deklarieren und deren Ersetzungen haben, kann es praktischer sein, einen Helfer zu verwenden

/**
 * Creating a deprecated / obsolete behavior for methods in a library.
 * [Credits]{@link: https://stackoverflow.com/q/21726472/1333836}
 * 
 * @param  {function} replacementFunction
 * @param  {string} oldFnName
 * @param  {string} newFnName
 * @return {function}
 */
const Oboslete = function(replacementFunction, oldFnName, newFnName) {
    const wrapper = function() {
       console.warn("WARNING! Obsolete function called. Function '" + oldFnName + "' has been deprecated, please use the new '" + newFnName + "' function instead!");

        replacementFunction.apply(this, arguments);
    }
    wrapper.prototype = replacementFunction.prototype;

    return wrapper;
}

Zusammenfassung

Ich würde vorschlagen, dass Ihr Team sich einigt und Veraltungspraktiken übernimmt, die für Ihr Projekt oder Ihren Anwendungsfall am sinnvollsten sind, sei es die Übernahme der hier behandelten Praktiken oder anderer.

Beachten Sie, dass es Zeiten gibt, in denen die Löschung sinnvoller ist als die Veraltung. Manchmal lohnt es sich einfach nicht, Aufwand in die Veraltung zu investieren. Wieder einmal liegt es ganz bei Ihnen und dem, was für Ihr Projekt am sinnvollsten ist.

Kennen Sie andere bewährte Praktiken, wenn Sie eine Methode in JavaScript als veraltet kennzeichnen? Lassen Sie es mich in den Kommentaren wissen!

Danksagungen

Die Ideen, die ich hier geteilt habe, wurden von Kommentaren inspiriert, die ich auf Software Engineering Stack Exchange und auf StackOverflow gefunden habe.