Sarebbe utile aggiungere un tag doc-comment @beta? [chiuso]

4

Quando una funzione ha raggiunto la fine della sua vita, aggiungiamo un tag @deprecated nel suo doc-comment per notificare agli altri sviluppatori che dovrebbero smettere di usare questa funzione, e poi un paio di anni dopo viene rimosso.

Stavo solo pensando a un tag @beta per indicare che questo metodo è nuovo di zecca e non è stato ancora testato in una varietà di casi d'uso.

Potresti pensare "puoi scrivere casi d'uso per assicurarne la correttezza!" Certo che puoi, ma è l'API che mi riguarda e come si comporta in casi limite. A volte queste decisioni non sono ovvie finché non hai provato la funzione in una varietà di situazioni. A volte è necessario aggiungere nuovi parametri per coprire più casi d'uso. A volte riordinarle ha senso se si scopre che un argomento è in realtà opzionale e deve essere spostato alla fine (o viceversa).

Aggiungendo il tag @beta , avvisi ad altri sviluppatori che l'API di questo metodo potrebbe ancora cambiare e dovrebbero utilizzarla con estrema cautela. Questo ti dà un controllo più granulare sulla tua API invece di rendere l'intero progetto 'beta'.

Per trarre il massimo vantaggio da questo, tuttavia, IDE e generatori di documentazione dovrebbero raccogliere questo tag.

Che cosa ne pensate voi ragazzi? Potresti vedere questo come utile, è una perdita di tempo, o hai altri modi per affrontare questo?

In passato, ho reso tali metodi "privati" laddove possibile, o li ho preceduti con un carattere di sottolineatura.

    
posta mpen 22.11.2013 - 18:58
fonte

3 risposte

1

Non è solo una perdita di tempo, è un'enorme perdita di tempo.

C'è una grande differenza tra @beta e @deprecated. L'uso di @deprecated va bene: informa gli utenti dell'API che il metodo, la funzione o la classe non saranno più utilizzati in futuro. Lo stato deprecato non cambierà mai fino a quando il blocco di codice non verrà eliminato dal codice sorgente attivo. Il codice obsoleto è il risultato secondario del codice più recente. Il sovraccarico del codice di marcatura come deprecato sta ricordando quale codice viene sostituito e pianificando quando rimuoverlo. È impossibile dimenticare di rimuovere il flag @deprecated, perché i metodi deprecati si trovano nella loro fase di fine vita. Potresti sostenere che il codice può anche essere sottostimato, ma in questo caso dovresti considerare seriamente la stabilità della tua API.

@beta informa gli utenti dell'api che possono utilizzare un membro dell'API a proprio rischio. Dimenticare di rimuovere la bandiera dalla documentazione si traduce in un enorme spreco di tempo per gli utenti, dal momento che saranno riluttanti a utilizzare metodi più recenti che ne risparmiano i tempi di sviluppo. È anche ridondante da una prospettiva del programmatore API, perché con un sistema di controllo della versione decente (che è decentemente utilizzato), è possibile ottenere una panoramica di ciò che è cambiato dall'ultima versione stabile.

Che ci porta alle versioni. Se la qualità di un blocco di codice è scarsa o troppo nuova o troppo instabile o troppo nulla, allora non dovrebbe essere rilasciata come codice stabile. Nelle menti degli utenti API, il link più debole nell'API farà a pezzi la sua reputazione, anche se contrassegnato come tale nella documentazione. Gli utenti più avventurosi che amano il pericolo e le funzionalità nascoste potrebbero voler ottenere una versione beta.

Oh, e non dire "ma i miei utenti sono molto intelligenti e faranno la differenza", perché, beh, per non parlare dell'intelligenza degli utenti dell'API, che potrebbe essere sopra moderata, preferiranno un ambiente pulito, stabile API su qualsiasi altra cosa per un lavoro serio.

La soluzione a questo problema risiede più nelle linee dell'uso intelligente del controllo di versione distribuito e della programmazione di rilascio che nella documentazione, che non si evolve sempre in sincronia con lo sviluppo del codice sorgente.

    
risposta data 27.12.2013 - 23:09
fonte
0

In realtà mi piace il tuo suggerimento. È una sorta di pre-cursore per aggiungere qualcosa come la parola "finale" davanti a una funzione. Ha molto senso, e mentre i commenti sopra suggeriscono che l'uso e i casi di test sono prudenti, spesso nel mondo reale non possiamo creare o persino vedere tutti i casi di test fino a quando qualcosa non si presenta.

    
risposta data 24.12.2013 - 20:05
fonte
-1

Non dovresti aggiungere funzionalità non testate o instabili a un'API stabile. Invece, aggiungili a un ramo beta / testing e quando sono abbastanza testati, aggiungi loro una nuova versione stabile. In caso contrario, gli utenti della tua API stabile dovranno costantemente verificare se i metodi che stanno utilizzando sono stabili.

    
risposta data 11.01.2014 - 19:02
fonte

Leggi altre domande sui tag