Come contrassegnare una classe come in sviluppo in Java

Perché non basta controllare tutte le classi instabili in un ramo diverso sul tuo sistema di controllo delle versioni?

Se hai commentato correttamente la classe potresti contrassegnare i bit di funzionalità incompleta come "deprecati" e commentare l'intestino del metodo e mettere un throw new UnsupportedOperationException(); .

Vedi Esiste qualcosa come NotImplementedException di .NET in Java? per i dettagli.

Non conosco questo avvertimento del compilatore.

Nella tua situazione probabilmente utilizzerei l'annotazione @Deprecated . Cancellerà le chiamate di metodo in modo che sia ovvio agli altri che qualcosa è successo. Quando guardano a cosa succede, vedranno i tuoi commenti su "non pronto per la produzione" e passeranno all'AHA.

Non penso che esista un metodo standard per marcare il codice come WIP , Incomplete o qualcosa del genere.

Potresti creare una nuova eccezione denominata ClassUnstableException e quindi innalzarla nel costruttore Class3 con un messaggio che spiega come non dovrebbero usarlo. Questo è un problema, perché li avverte solo in fase di esecuzione.

Potresti anche provare a rendere la classe incomparabile in qualche modo, e poi aggiungere una nota alla sezione di codice che fa scattare il compilatore in modo che se qualcuno va a correggere il codice, si spera veda un spiegazione di perché non dovrebbero usare quella classe. Questo potrebbe non funzionare se usano uno strumento semi-automatico di "correzione di questo problema" che alcuni IDE hanno. Questo è anche male perché potrebbe interrompere le build.

Potresti creare un'annotazione denominata WIP (poiché la cosa più vicina a cui riesco a pensare è Deprecated ma non significa realmente la stessa cosa) e usarla per annotare la classe. Questo probabilmente sarebbe un po 'più di lavoro, e cosa sosterrebbe l'annotazione?

Infine, puoi semplicemente inserirlo nei commenti, ma funzionerà solo se le persone effettivamente leggono .

EDIT:

Può essere rilevante: Come intenzionalmente causare un messaggio di avviso del compilatore java personalizzato?

potresti introdurre elaborazione delle annotazioni temporali di compilazione ma ciò imporrebbe membri del team per regolare il processo di compilazione.

Tuttavia trovo l'intero processo un po 'confuso. Un'API instabile dovrebbe essere chiaramente separata creando un ramo nel sistema di controllo della versione. Se davvero deve essere nel resto della base di codice, è stato documentato come instabile e tuttavia viene utilizzato il problema non è molto tecnico ma si trova all'interno dell'organizzazione e della comunicazione. Sì, potresti introdurre verifiche tecniche (come l'elaborazione delle annotazioni) ma questo non risolverebbe il problema, ma lo sposterai su un altro livello.

Quindi la mia raccomandazione è: se non puoi separare il codice base mettendolo in rami diversi, allora parlare alle persone e spiegare loro perché non devono usare il API.

Perché è lì al primo posto?

Hai controllato il codice instabile nella linea principale? Perché?

Il codice instabile non deve essere controllato in trunk / main / master o qualunque sia il nome del trunk principale. Questo è considerato uno sviluppo ad alto rischio e dovrebbe invece essere sequestrato nel suo stesso ramo su cui hai lavorato piuttosto che controllato in main.

Incoraggio strongmente te (e il tuo team principale) a leggere Strategie di ramificazione avanzata di SCM . In particolare, prestate attenzione al ruolo di sviluppo e cosa dice su ciò che è considerato uno sviluppo ad alto rischio:

In general, consider using separate branches for each high-risk project. High risk projects are characterized by large size, large numbers of people, unfamiliar subject matter, highly technical subject matter, very tight time lines, uncertain delivery dates, incomplete or volatile requirements, and geographically distributed project teams. Similarly, consider designating a single branch for low risk development in each release. Several sources including [WING98] recommend using the mainline for this purpose. Consider the factors discussed above for the mainline before committing to this course of action. Low risk development may have different policy from the mainline even if you have multiple members of a product family coordinating through the mainline.

Lasciare che le persone controllino il codice instabile (o non utilizzato) nella linea principale significa che confonderai i futuri sforzi di sviluppo per provare a mantenere questo codice. Ogni ramo e clone del rappresentante da ora fino alla fine dei tempi conterrà questo fino a quando qualcuno dice "il suo codE morto" e lo cancella.

Ci sono alcuni che dicono "bene, se è in un ramo si dimenticano" e mentre quello può essere vero, avendo dimenticato il codice morto (e instabile) nella linea principale è molte volte peggiore in quanto confonde tutti gli sviluppi futuri finché non è rimosso - e quindi è ancora più dimenticato. Un ramo ben definito di "/ fooProject / branches / WeisBigIdea" (o equivalente) è visibile e più facile da utilizzare in futuro, specialmente se funziona.

@Deprecated

La prima cosa è l'annotazione @Deprecated . Questo va oltre la javadoc e sputa gli avvertimenti del compilatore. javac fornisce un flag -deprecation che è descritto come:

Show a description of each use or override of a deprecated member or class. Without -deprecation, javac shows a summary of the source files that use or override deprecated members or classes. -deprecation is shorthand for -Xlint:deprecation.

Come notato, questo va ben oltre gli avvertimenti del compilatore standard.

In molti IDE, i metodi e i valori deprecati sono mostrati con una barratura:

foo.bar();

E produrrebbe un risultato come:

$ javac -Xlint:all Foo.java Bar.java
Bar.java:2: warning: [deprecation] Foo in unnamed package has been deprecated
interface Bar extends Foo { }
                      ^

A seconda della struttura di costruzione, potresti avere avvertenze che interrompono la compilazione. Questo solo interrompe la compilazione se è stata usata una delle tue classi (non se è semplicemente compilata).

@CustomAnnotation

Ci sono molti approcci a questo. Ad esempio, l' annotazione javac @Warning leggero che fornisce un processore di annotazioni che attiva un avviso in fase di compilazione quando qualcosa con quell'annotazione viene utilizzato ( un tutorial netbeans sui processori di annotazione personalizzati in modo da farti un'idea di cosa succede dietro le quinte).

Oracle descrive anche un esempio di utilizzo di annotazioni personalizzate per un'annotazione @Unfinished in Making la maggior parte dei metadati di Java, parte 2: annotazioni personalizzate .

Con AnnotationProcessor , puoi eseguire codice arbitrario al momento della compilazione. Dipende davvero da te decidere cosa vuoi che faccia. Avverti, rompi la build quando qualcosa viene usato. Ci sono numerosi tutorial sul Web per come scrivere questo tipo di codice. Se vuoi generare un errore quando è compilato (questo sarà fastidioso e porterà a essere cancellato) o se è usato (un po 'più complesso da scrivere).

Si noti che tutto ciò implica la modifica delle build per utilizzare effettivamente il processore di annotazione.

Potresti spostare tutte le classi incomplete in un sotto pacchetto con qualcosa di ovvio come "NOTCOMPLETE"? È un po 'un trucco, ma potrebbe essere abbastanza visibile.

(Se non sono tutti nello stesso pacchetto, potresti ricreare la struttura del pacchetto qui sotto.)

Non so che ci sia davvero un buon modo per farlo nel codice. Fai un passo indietro:

Crea due copie dell'intero progetto, una con la classe e l'altra senza. Contrassegnare la versione senza la classe come base di codice stabile, pronta per la versione di produzione e la versione con la classe come sviluppo per una versione futura. Documenta cosa deve succedere prima che questa classe possa essere considerata di qualità di produzione.

Idealmente, dovresti farlo usando i rami nella soluzione di controllo del codice sorgente che preferisci. Potresti dover imbrogliare un po ', dato che sembra che tu non stia usando una strategia di ramificazione del genere. Rimuovere con cautela la nuova classe, controllare una versione senza di essa e fare alcuni test di regressione. Quando sei soddisfatto è stabile, puoi taggare quella revisione, creare un ramo di sviluppo dal tag e quindi aggiungere la classe nel ramo di sviluppo.

Io opterei per fare astrazione della classe, e commentare in modo appropriato - in questo modo, il codice è ancora lì per riferimento, ma buona fortuna a chiunque tenti di istanziarlo:)

Che ne pensi di creare una dipendenza che il compilatore non può risolvere? Basta aggiungere:

import this.is.not.done.yet.do.not.use.it;

in alto. Gli utenti non potranno compilare con esso.

Se vuoi testare la classe, crea semplicemente un pacchetto / classe con quel nome (o usa uno più semplice come "experimental.danger") e puoi testare il nuovo codice.