Come utilizzare correttamente le annotazioni @CheckForNull, @Nonnull e @Nullable di FindBug

Question

Desidero formalmente annotare le firme delle funzioni per chiarire i loro contratti, specialmente se i parametri null e i valori restituiti sono consentiti o vietati, in modo che FindBugs " lo strumento di analisi del codice statico (e forse altro) può farne uso.

Ci sono due pacchetti (annotations.jar e jsr305.jar) con quattro annotazioni ciascuno per raggiungere questo obiettivo, oltre all'opzione di non inserire alcuna annotazione.

Answer 1

Questi sono i miei risultati dopo qualche tentativo in giro:

parametri Metodo:

• parametro non deve essere null: Non inserire annotazioni. In questo caso viene visualizzato un segno di errore se il metodo passa a null. (Mi aspettavo questo comportamento quando mettendo il @Nonnull di annotazione, ma quando l'ho messo, nessun marcatore bug è venuto fino a tutti.)
• parametro può essere null: Put @Nullable annotazione. . (Stesso effetto per @CheckForNull Il @Nullabledocumentation legge: “FindBugs tratteranno gli elementi annotati come se non avessero alcuna annotazione.” Questo non è vero se io chiamo string.length() e String string è stata segnata @Nullable, provoca un marcatore bug a comparire. , se non c'è nessun annotazione marcatore bug mostrato)

Metodo valore di ritorno:.

• metodo non mai tornare nulla: Put @Nonnull. Provoca un indicatore di errore se si prova a return null; dall'interno del metodo.
• Metodo can ritorno null: Vuoi applicare controlli per questo? I controlli possono essere un overhead se il valore di ritorno dipende solo dai parametri del metodo che si possono presumere noti al momento della chiamata, come "il mio metodo restituisce null se il parametro uno è negativo". Non metterei un'annotazione in quel caso. Tuttavia, potresti prendere in considerazione la possibilità di lanciare un valore IllegalArgumentException invece di restituire null.
• Il metodo può restituire null e l'oggetto di reso deve sempre essere controllato: Put @CheckForNull. Tuttavia, in molti casi ci sono modi migliori per andare, potresti prendere in considerazione la possibilità di restituire gli elenchi null anziché MissingResourceException, IOException o un'altra eccezione appropriata.

Quale file JAR da usare:

• Entrambi i file jar provocano lo stesso comportamento del FindBugs, l'unica differenza è che le annotazioni da annotations.jar stanno mostrando come deprecato in Eclipse. Quindi utilizzare jsr305.jar.
• Il file jar è necessario. La creazione di annotazioni vuote con il pacchetto e il nome della classe forniti non funziona. È possibile get it here.

Answer 2

@Paramaeleon ha dato ottimi consigli, ad esempio come si deve lasciare un parametro di metodo non annotate perché FindBugs sopprime unintuitively tutti gli avvisi se si scrive @Nonnull.

Se si desidera provare un altro strumento di analisi statica, è possibile prendere in considerazione lo Nullness Checker dello Checker Framework.

La differenza principale è che Nullness Checker ha lo scopo di rilevare tutti gli errori del puntatore nullo. Al contrario, FindBugs intenzionalmente non segnala alcuni possibili errori, al fine di segnalare un minor numero di avvisi falsi positivi. Entrambi gli strumenti danno risultati migliori più annotazioni scrivi. Se non sei disposto a scrivere annotazioni, allora FindBugs è uno strumento più appropriato. Se sei disposto a scrivere annotazioni, allora il Checker Framework potrebbe essere migliore.

Il manuale Nullness Checker contiene ulteriori confronti nella relativa sezione su choosing a nullness analysis tool.