Tilnærminger til Deprecating Kode i JavaScript

0
33

Nylig, jeg måtte grave seg inn i temaet koden for avskrivninger i JavaScript. Jeg føler at dette emnet blir mindre dekning, selv om det kan spille en viktig rolle i enkelte prosjekter, spesielt når du arbeider i større grupper eller arbeider med eksternt Api-er.

I JavaScript-land, jeg vet ikke av noen sanne industristandarder for deprecating JavaScript. Det kan være annerledes i et team, bibliotek eller en leverandør.

Det er derfor mitt mål her er å oppsummere mine funn og tanker om dette emnet, sammen med noen gode øvelser når det er tid for å markere en JavaScript-metode foreldet en codebase.

Hva betyr “nedgradering” egentlig betyr?

La oss først starte med å presisere at nedgraderingen er bare en status brukes til programvaren funksjonen. Det indikerer at denne funksjonen bør unngås, vanligvis fordi det har blitt erstattet.

Nedgraderingen kan også indikere at funksjonen vil bli fjernet i fremtiden. Funksjonene er deprecated—snarere enn umiddelbart fjernet for å gi tilbakevirkende kompatibilitet, og gi programmerere som har brukt de har tid til å ta med kode i samsvar med den nye standarden.

I tillegg, en utdatert funksjonen tyder på at det ikke vil være noen videre utvikling fra dette punktet og utover. Det bør ikke fungerer noe annerledes enn det gjorde i en tidligere versjon (mindre dokumentasjon uttrykkelig sier noe annet). Så, generelt, det bør være den samme som den var da nedgraderingen handlingen skjedde.

Det kan eller ikke kan jobbe i den nyeste versjonen—ingen garantier!

Imidlertid, siden det ikke er noen sanne industristandarder som er strengt fulgt inJavaScript-land, kan dette være litt annerledes per lag, bibliotek eller en leverandør.

Når du skal deprecate kode og når du skal slette det?

Det er viktig å merke seg at en utdatert programvare funksjonen eller metoden er fortsatt en del av programvaren! Vurdere “deprecated” etikett som bare en status av koden. Om programvaren har faktisk vil bli fjernet i fremtiden er avhengig av hva den aktuelle programvaren teamet bestemmer seg for.

I min mening, store team eller prosjekter å stole på eksterne Api-er eller biblioteker bør deprecate først, for så å fjerne senere (etter en rimelig tid, men du definerer det). I det minste, gi minst ett større versjon bump før du faktisk fjerner ugyldig kode, slik at brukerne har en sjanse til å tilpasse seg endringen.

Du ønsker kanskje å se på Semantisk Versjonskontroll, et enkelt sett av regler og krav som dikterer hvordan versjon nummer er tildelt og øker. Gitt en versjon nummer for STORE.MINDRE.PATCH, increment den STORE versjonen når du gjør uforenlig API endringer, MINDRE versjonen når du legge til funksjonalitet i en bakover-kompatibel måte, og OPPDATERINGEN versjon når du gjør bakover-kompatibel feilrettinger.

Hvis programvaren er i rask endring og utvikling, og du er deprecating en funksjon, kan du prøve å kommunisere med dine prosjektleder hvis denne funksjonen er forventet å oppstå senere. Hvis du velger å deprecate, i stedet for å slette, kan det være mye enklere for deg å gå, bør du må.

For mindre grupper eller prosjekter med interne metoder og Api-er, gå videre og ta første snarere enn deprecate. Noen ganger er det bare ikke gir mening å kaste bort tid og nedgraderingen bare øker kompleksiteten bare for skyld for de beste løsningene.

Hvordan å markere en metode foreldet

Her er fem gode rutinene jeg har funnet det mest nyttige:

  1. Legg til en @deprecated JSDoc flagg.
  2. Nevne den versjonen som metoden ble avverget.
  3. Finne ut en tidsramme for når denne metoden vil bli slettet, inkludert hvilken versjon det vil ta sted. Ellers, basert på min erfaring, det forblir for alltid 🙂
  4. Bruk kommentarer villig til å forklare gjennomføring, til fordel for andre utviklere eller din fremtidige selv. Dette er svært nyttig hvis din bruk-saken er å skrive et bibliotek som andre bruk som en avhengighet for sitt arbeid.
  5. Legg til en konsoll advarsel som indikerer at funksjonen er ugyldig.

Her er en mer praktisk eksempel hvor jeg bruker alle fem praksis:

/**
* En magisk metode som flere sifre.
*
* @utdatert [#1] siden versjon 2.3 [#2].
* [#3], Vil bli slettet i versjon 3.0.

* [#4] I tilfelle du trenger lignende atferd, implementere det på deg selv,
* fortrinnsvis i vanilje JavaScript
* eller bruk multiplyTheSameNumber metode i stedet,
* hvis det samme tallet behov for å bli multiplisert flere ganger, som så:
* multiplyDigits([5, 5, 5]) === multiplyTheSameNumber(5, 3)
*
* @param {array} _digits – siffer for å multiplisere
*/
funksjonen multiplyDigits(_digits) {
– konsollen.advare(“Kalle en metode depricated!”); // [#5]

// ….
}

For å unngå gjentakelse i konsollen advarsler eller i tilfelle du planlegger å deprecate flere metoder, og du har deres erstatninger, kan det være mer praktisk å bruke en hjelper:

/**
* Opprette en utdatert / foreldet atferd for metoder i et bibliotek.
* [Studiepoeng]{@link: https://stackoverflow.com/q/21726472/1333836}
*
* @param {funksjon,} replacementFunction
* @param {string} oldFnName
* @param {string} newFnName
* @return {funksjon,}
*/
const Oboslete = function(replacementFunction, oldFnName, newFnName) {
const wrapper = function() {
– konsollen.advare(“ADVARSEL! Foreldet funksjonen kalles. Funksjonen ‘” + oldFnName + “‘ har blitt avverget, vennligst bruk den nye ‘” + newFnName + “‘ – funksjonen i stedet!”);

replacementFunction.legge til dette, argumenter);
}
wrapper.prototypen = replacementFunction.prototype;

tilbake wrapper;
}

Innpakning opp

Jeg foreslår at du får ditt lag på samme side og arve nedgraderingen praksis som passer best for dine prosjekt og / eller bruk tilfelle, om det er å vedta den praksis vi har dekket her eller andre.

Merk at det er enkelte ganger når sletting er mer fornuftig enn for avskrivninger. Noen ganger, å investere innsats for å deprecate noe rett og slett ikke verdt det. Igjen, det er helt opp til deg og hva som er mest fornuftig for prosjektet.

Vet du om andre gode eksempler når det markerer en metode foreldet i JavaScript? Gi meg beskjed i kommentarfeltet!

Studiepoeng

Ideene jeg har delt her var inspirert av kommentarene jeg har funnet på Software Engineering Stack Exchange og på StackOverflow.