Blocca l'API

L'arte di costruire efficacemente un'API riguarda tanto la gestione delle aspettative quanto la struttura.

Quando dico API, mi riferisco specificamente a come vengono denominate le classi / metodi pubblici / interni e qual è il loro livello di accesso (cioè privato / pubblico / interno).

Se sei preoccupato che il codice potrebbe non essere completamente pronto per la prima serata, puoi sempre pubblicarlo inizialmente come beta.

Uscite:

• Beta (cioè pre 1.0)

  • può contenere più modifiche alle interruzioni API
  • potrebbe mancare di modifiche alla retrocompatibilità tra le versioni
  • potrebbe avere una mancanza di smalto

• Official (1.0 +)

  • API è bloccato fino alla prossima versione principale
  • eventuali modifiche introdotte dovrebbero garantire la compatibilità con le versioni precedenti

• Minore (ex 1.1)

  • contiene correzioni di errori e / o implementazioni di funzionalità
  • potrebbe aggiungere ma non togliere l'API definita

Se pensi che l'API abbia bisogno di essere temprata dalla battaglia, allora rilasciala per un po 'come beta. Ciò indica che è disponibile per l'uso ma non dovrebbe essere utilizzato per il codice di produzione e / o mission-critical.

Molte persone trattano schemi di versionamento numerati come hogwash, ma quando vengono utilizzati in modo efficace possono essere utilizzati per fornire un po 'di spazio di manovra finché non si risolve la struttura.

Le tue ipotesi su come verranno utilizzate sono sbagliate

Indipendentemente dal modo in cui qualcosa è stato progettato, le persone troveranno un modo per abusare o creare un uso alternativo.

Un modo per gestirli è bloccare il più possibile l'implementazione utilizzando gli accessor (cioè privati / pubblici / interni) ma nessuna quantità di progettazione o ingegneria ti darà più informazioni che rilasciare il codice agli utenti.

Non importa quanto "perfetto" pensi che il tuo codice possa diventare, i tuoi utenti dimostreranno che non lo è.

Direi che questo è il motivo principale per cui è sempre meglio usare una base di codice esistente piuttosto che una riscrittura completa. Nel migliore dei casi, una riscrittura completa ridurrà l'espansione, ma è molto probabile che la nuova base di codice conterrà tutti i bug (e forse più) della base di codice originale.

Nel tuo caso sei indolenzito da zero, quindi potresti anche iniziare.

Sembra che tu abbia coperto il resto delle tue basi. La documentazione dell'API è di vitale importanza e i test saranno utili per garantire la stabilità quando verranno apportate modifiche in futuro.

L'implementazione di uno schema di registrazione coerente sarà importante prima che il codice venga rilasciato per la produzione perché sarà necessario un modo per abilitare / disabilitare / filtrare globalmente i registri. A proposito, nella maggior parte dei casi la registrazione riguarda solo l'importazione di una libreria e la modifica delle chiamate in uscita da Debug.WriteLine () a qualcosa come Logging.Debug (), Logging.Info (), Logging.Error (). Lo stesso logger fornisce solo un'implementazione standard per la configurazione, il filtraggio e una gamma più ampia di schemi di output (ex file, console, ecc.).

Oltre a questo, cercherò di estrarre il codice e di usarlo. Anche se solo da un piccolo numero di utenti per iniziare.

Queste sono due cose che trovo sono la chiave per il rilascio del software:

• Conosci esattamente ciò che hai rilasciato
• Gestisci le aspettative

Vuoi essere in grado di tornare indietro e correggere i bug che hai rilasciato e vuoi che le persone capiscano quale problema il tuo codice risolverà.

Sapendo cosa hai rilasciato

Assicurati di averlo correttamente versionato e firmato (se appropriato). Usa il tuo controllo del codice sorgente per contrassegnare \ etichettare il codice associato alla versione ufficialmente rilasciata. Questo ti aiuterà a identificare i bug in modo più semplice, dato che puoi tornare esattamente al codice sorgente che hai rilasciato. Aiuterà anche in futuro quando potresti avere diverse versioni rilasciate.

Cerca di rendere l'ultima versione facile da reperire e aggiornare. Che si tratti di un programma di installazione o semplicemente di metterlo su una condivisione comune dipende da chi \ quando \ con che frequenza spedirai.

Assicurati di avere qualcuno che riveda la tua versione finale, inclusa la documentazione. È molto facile diventare nervosi o entusiasti di rilasciare software e perdere qualcosa.

Gestione delle aspettative

Documenta i limiti e rendili ragionevolmente ovvi per gli sviluppatori. È bello averli trovati. Le persone spesso capiscono meglio se conoscono i limiti del tuo software, soprattutto se hai un piano per risolverli.

Documenta come vorresti un feedback, buono o cattivo. Dato che si tratta di un progetto interno, se tutti hanno accesso a un sistema di tracciamento dei bug comune, chiedi loro di presentare bug relativi al progetto appropriato.

In futuro, evita di cambiare l'API se possibile, questa è l'unica cosa che può potenzialmente infastidire i tuoi clienti. Ricorda che anche le eccezioni fanno parte dell'API, anche se in C # non fanno parte della documentazione del metodo. potrebbe essere possibile migliorare le eccezioni lanciate in un secondo momento, ma dovrai parlare con gli utenti finali e vedere quale impatto avrà.

Ho una lista di controllo per le distribuzioni che potresti trovare utile. Realizzo desktop, ma alcuni di questi dovrebbero essere tradotti. Eccone alcuni:

Generale:

• Inserisci controlli null per i parametri di funzione che non dovrebbero essere nulli. Questo mi aiuta a fallire presto.
• Rimuovi commenti non necessari e file commentati. Questi causano il lavoro futuro.
• Cerca qualsiasi commento "// TODO". A volte lascio appunti per me stesso. A volte me ne dimentico.
• Esegui un test del mio codice utilizzando il database di produzione, ove possibile. Questo aiuta a garantire che tutte le modifiche al mio database siano presenti sul server di produzione.
• Inserisci copiosi loghi. Soprattutto per una distribuzione iniziale. In effetti, salvo il logging per la fine, il mio codice è solitamente gelificato a questo punto. Non vuoi essere in una situazione in cui hai un incidente e dici a te stesso "Se solo sapessi qual è il valore di X in questo momento". Prova a pianificare in anticipo.
• Prova a racchiudere le chiamate di libreria di terze parti in Facciate. In questo modo è facile cambiare le librerie in futuro e fornisce una lista di controllo di ciò che ti serve da una libreria.

. Specifica specifica:

• Assicurati di chiamare Dispose () su oggetti usa e getta. Uso Code Analysis o FxCop per aiutare a trovare casi di questo.
• Assicurati di sganciare correttamente tutti i gestori di eventi. Ciò impedisce perdite di memoria.