Spedizione della mia biblioteca di prima classe. Qualche problema che devo conoscere?


12

Sono uno sviluppatore web che sta per sbloccare il risultato "First Class Library Published" nella mia carriera e sto sudando proiettili (sono stato sveglio tutta la notte stressandomi). Mi piacerebbe toccare l'esperienza della community per vedere se qualcuno ha suggerimenti o raccomandazioni per assicurarsi che tutto vada per il meglio. Ci sono dei dettagli o dei dettagli di cui devo essere consapevole? Qualcosa di speciale nel processo di compilazione che può tornare a mordermi?

Ecco dove sono:

  • La libreria è testata dall'unità e ha una copertura del codice del 97% circa
  • L'API è ben documentata e sono stati creati documenti xml per il supporto di intellisense
  • Ho assicurato che gli accessi di classe pubblici / privati ​​siano accurati e corretti. Lo stesso vale per tutti i getter / setter
  • La gestione degli errori non è così aggraziata come vorrei che fosse, ma sono contro una scadenza e ho ammesso che è un "buono come sarà" per ora
  • Nessuna registrazione amichevole. Debug.Writeline è stato ampiamente utilizzato ... Ho imparato di recente che questo è un riflesso della mia inesperienza :(

Il tuo consiglio è molto apprezzato!

La libreria verrà utilizzata per generare report. Cappello standard: si collega al database di sola lettura, esegue calcoli, formati e trasmette i dati al flusso di risposta.


Sono stato sfruttato come risorsa marginale da compilare per uno dei programmatori che ha abbandonato e questo compito mi è stato assegnato come progetto "taglia i denti". La libreria di classi verrà rilasciata per essere utilizzata da altri programmatori dell'azienda durante la scrittura del codice di produzione.


2
Hai bisogno di dettagli, rilascia come? Rilascio in vendita? Rilasciare open-source per la condivisione? Rilascio a un cliente per un contratto in corso? Rilascio al resto della tua organizzazione di sviluppo come parte di un progetto per il tuo datore di lavoro a tempo pieno? Rilascio come versione 1.0 di un nuovo prodotto per la disponibilità del cliente per il tuo datore di lavoro a tempo pieno?
Jimmy Hoffa,

@JimmyHoffa: aggiunte risposte alle tue domande. Grazie per averci dedicato del tempo!
Mr. JavaScript

1
Fai finta di essere un utente della biblioteca senza sapere come funziona. Usalo per costruire qualcosa. Cambia / rimuovi / aggiungi elementi in base all'esperienza. Quindi rilascialo a utenti reali e ottieni il loro feedback.
mike30,

Forse usi Sandcastle o altre librerie che generano documenti per avere materiale di riferimento offline (ish)?
Jesse C. Slicer,

7
Rilassare. Avere persino un singolo test unitario e una sola riga di documentazione API eleva già questa versione al di sopra del ~ 95% del codice "rilasciato per essere utilizzato da altri programmatori dell'azienda", nella mia esperienza.
Carson63000,

Risposte:


8

Blocca l'API

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

Quando dico API, mi riferisco in modo specifico a come vengono denominati i metodi / classi pubblici / interni e quale è il loro livello di accesso (cioè privato / pubblico / interno).

Se temi 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 alla rottura dell'API
    • potrebbero mancare modifiche di retrocompatibilità tra le versioni
    • potrebbe avere una mancanza di smalto
  • Ufficiale (1.0+)

    • L'API è bloccata fino alla prossima versione principale
    • eventuali modifiche introdotte dovrebbero garantire la retrocompatibilità
  • Minore (ex 1.1)

    • contiene correzioni di bug e implementazioni di funzionalità
    • può aggiungere ma non rimuovere l'API definita

Se ritieni che l'API debba essere rafforzata in battaglia, rilasciala per un po 'come beta. Ciò indica che è disponibile per l'uso ma non deve essere utilizzato per codice di produzione e / o mission-critical.

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

I tuoi presupposti su come verrà utilizzato sono sbagliati

Non importa quanto bene sia progettato qualcosa, le persone troveranno un modo per abusare o creare un uso alternativo.

Un modo per gestirlo è bloccare la maggior parte possibile dell'implementazione usando gli accessor (cioè privati ​​/ pubblici / interni) ma nessuna quantità di progettazione o ingegneria ti fornirà più informazioni sul rilascio del 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 eseguire una riscrittura completa. Nella migliore delle ipotesi, una riscrittura completa taglierà il gonfiore, ma è molto probabile che il nuovo codebase contenga tanti (e forse più) bug del codebase originale.

Nel tuo caso stai combattendo da zero, quindi potresti anche iniziare.


Sembra che tu abbia coperto il resto delle tue basi. La documentazione dell'API è vitale e i test saranno utili per garantire la stabilità in caso di 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 i registri a livello globale. A proposito, nella maggior parte dei casi la registrazione comporta solo l'importazione di una libreria e la modifica delle chiamate di output da Debug.WriteLine () a qualcosa come Logging.Debug (), Logging.Info (), Logging.Error (). Il logger stesso fornisce solo un'implementazione standard per la configurazione, il filtro e una gamma più ampia di schemi di output (ex file, console, ecc.).

A parte questo, vorrei cercare di ottenere il codice e di usarlo. Anche se solo da un numero limitato di utenti per iniziare.


1
+1 Ri: registrazione - Consiglio vivamente TraceSource . Non introduce dipendenze esterne poiché fa parte delle librerie .NET di base e consente agli utenti di collegare listener e configurare la traccia sia attraverso il codice che attraverso i file app.config.
Dan Lyons,

4

Queste sono due cose che trovo fondamentali per il rilascio di software:

  • Sai esattamente cosa hai rilasciato
  • Gestire le aspettative

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

Sapendo cosa hai rilasciato

Assicurati di averlo correttamente aggiornato e firmato (se disponibile). Usa il controllo del codice sorgente per taggare \ etichettare il codice associato alla versione ufficialmente rilasciata. Questo ti aiuterà a identificare più facilmente i bug in quanto puoi tornare esattamente al codice sorgente che hai rilasciato. Aiuterà anche verso il basso quando potresti avere diverse versioni rilasciate.

Prova a rendere l'ultima versione facile da ottenere e aggiornare. Che si tratti di un programma di installazione o semplicemente di inserirlo in una condivisione comune dipende da chi \ quando \ con quale frequenza spedirai.

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

Gestire le aspettative

Documentare le limitazioni e renderle ragionevolmente ovvie per gli sviluppatori. È bello che tu li abbia trovati. Le persone sono spesso più comprensibili se conoscono i limiti del tuo software, soprattutto se hai un piano per risolverli.

Documenta come desideri un feedback, positivo o negativo. Poiché si tratta di un progetto interno, se tutti hanno accesso a un sistema di tracciamento dei bug comune, chiedi loro di archiviare bug contro il progetto appropriato.

In futuro, se possibile, evitare di modificare l'API, 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. Esso può essere possibile migliorare le eccezioni gettati in un secondo momento, ma sarà necessario parlare con gli utenti finali e vedere quale impatto avrà.


0

Ho una lista di controllo per le distribuzioni che potresti trovare utili. Faccio sviluppo desktop ma alcuni di questi dovrebbero tradursi. Eccone alcuni:

Generale:

  • Inserire i controlli null per i parametri delle funzioni che non dovrebbero essere null. Questo mi aiuta a fallire presto.
  • Rimuovere i commenti non necessari e i file commentati. Questi causano lavori futuri.
  • Cerca eventuali commenti "// TODO". A volte lascio appunti per me stesso. A volte me ne dimentico.
  • Esegui un test del mio codice utilizzando, ove possibile, il database di produzione. Questo aiuta a garantire che tutte le modifiche al mio database siano attive sul server di produzione.
  • Inserire una registrazione abbondante. Soprattutto per una distribuzione iniziale. In effetti, salvo la registrazione per il salvataggio, alla fine perché 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 quale fosse il valore di X in questo momento". Prova a pianificare in anticipo.
  • Prova ad avvolgere le chiamate in libreria di terze parti in Facciate. Ciò semplifica la modifica delle librerie in futuro e fornisce un elenco di controllo di ciò che è necessario da una libreria.

.Net specifico:

  • Assicurati di chiamare Dispose () su oggetti usa e getta. Uso Code Analysis o FxCop per trovare casi di questo.
  • Assicurati di sganciare correttamente tutti i gestori di eventi. Questo impedisce perdite di memoria.
Utilizzando il nostro sito, riconosci di aver letto e compreso le nostre Informativa sui cookie e Informativa sulla privacy.
Licensed under cc by-sa 3.0 with attribution required.