Versand meiner erstklassigen Bibliothek. Gibt es irgendwelche Fallstricke, auf die ich achten muss?

12

Ich bin ein Webentwickler, der kurz davor steht, die "First Class Library Published" -Errungenschaft in meiner Karriere freizuschalten, und ich schwitze vor Kugeln (ich war die ganze Nacht auf und habe mich gestresst). Ich würde gerne die Erfahrung der Community nutzen, um zu sehen, ob jemand Vorschläge oder Empfehlungen hat, um sicherzustellen, dass dies so reibungslos wie möglich verläuft. Gibt es irgendwelche Besonderheiten oder Fallstricke, auf die ich achten muss? Gibt es etwas Besonderes an dem Build-Prozess, das mich beißen kann?

Hier bin ich:

  • Die Bibliothek ist Unit-getestet und verfügt über eine Codeabdeckung von ca. 97%
  • Die API ist gut dokumentiert und XML-Dokumente für die Intellisense-Unterstützung wurden erstellt
  • Ich habe dafür gesorgt, dass die Zugriffsberechtigten für öffentliche / private Klassen korrekt und korrekt sind. Das gleiche gilt für alle Getter / Setter
  • Fehlerbehandlung ist nicht so anmutig, wie ich es gerne hätte, aber ich stehe vor einer Frist und habe akzeptiert, dass sie vorerst "so gut ist, wie sie sein wird"
  • Keine freundliche Protokollierung. Debug.Writeline wurde ausgiebig genutzt ... Ich habe kürzlich erfahren, dass dies ein Spiegelbild meiner Unerfahrenheit ist :(

Ihr Rat wird sehr geschätzt!

Die Bibliothek wird zum Generieren von Berichten verwendet. Standard Hat - Stellt eine Verbindung zur schreibgeschützten Datenbank her, führt Berechnungen durch, formatiert und gibt Daten an den Antwortdatenstrom aus.


Ich wurde als Randressource für einen der Programmierer, die kündigten, angezapft, und diese Aufgabe wurde mir als Projekt "Schneiden Sie Ihre Zähne" übertragen. Die Klassenbibliothek wird freigegeben, damit andere Programmierer im Unternehmen sie verwenden können, während sie Produktionscode schreiben.

Herr JavaScript
quelle
2
Benötigen Sie Details, geben Sie frei, wie? Zum Verkauf freigeben? Open Source zum Teilen freigeben? Freigabe an einen Kunden gemäß eines Vertrags, den Sie abgeschlossen haben? Freigabe für den Rest Ihrer Entwicklungsorganisation als Teil eines Projekts für Ihren Vollzeitarbeitgeber? Release als v1.0 eines neuen Produkts zur Kundenverfügbarkeit für Ihren Vollzeitarbeitgeber?
Jimmy Hoffa
@JimmyHoffa: Antworten auf Ihre Fragen hinzugefügt. Danke, dass du dir die Zeit genommen hast!
Herr JavaScript
1
Stellen Sie sich vor, Sie sind ein Benutzer der Bibliothek und wissen nicht, wie sie funktioniert. Verwenden Sie es, um etwas zu bauen. Ändern / Entfernen / Hinzufügen von Dingen basierend auf der Erfahrung. Geben Sie es dann für echte Benutzer frei und holen Sie sich ihr Feedback.
mike30
Verwenden Sie möglicherweise Sandcastle oder eine andere Dokumentenerzeugungsbibliothek, um offline (ish) Referenzmaterial zu haben?
Jesse C. Slicer
7
Entspannen. Mit nur einem einzigen Unit-Test und einer einzigen Zeile API-Dokumentation liegt diese Version meiner Erfahrung nach bereits über 95% des Codes, der für andere Programmierer im Unternehmen freigegeben wurde.
Carson63000

Antworten:

8

Sperren Sie die API

Bei der Kunst, eine API effektiv zu erstellen, geht es sowohl um das Verwalten von Erwartungen als auch um die Struktur.

Wenn ich API sage, beziehe ich mich speziell darauf, wie die öffentlichen / internen Klassen / Methoden benannt sind und wie ihre Zugriffsebene lautet (dh privat / öffentlich / intern).

Wenn Sie befürchten, dass der Code zur Hauptsendezeit möglicherweise nicht vollständig bereit ist, können Sie ihn zunächst immer als Beta-Version veröffentlichen.

Veröffentlichungen:

  • Beta (dh vor 1.0)

    • kann mehrere API-Änderungen enthalten
    • Möglicherweise fehlen Änderungen der Abwärtskompatibilität zwischen den Versionen
    • kann ein Mangel an Polnisch haben
  • Offiziell (1.0+)

    • Die API ist bis zur nächsten Hauptversion gesperrt
    • Alle vorgenommenen Änderungen sollten die Abwärtskompatibilität gewährleisten
  • Moll (ex 1.1)

    • Enthält Bugfixes und / oder Feature-Implementierungen
    • kann der definierten API hinzugefügt, aber nicht entfernt werden

Wenn Sie der Meinung sind, dass die API kampferprobt werden muss, geben Sie sie für eine Weile als Beta frei. Dies bedeutet, dass es zur Verwendung verfügbar ist, jedoch nicht für produktions- und / oder geschäftskritische Codes verwendet werden sollte.

Viele Leute behandeln nummerierte Versionsschemata wie Hogwash, aber wenn sie effektiv eingesetzt werden, können sie verwendet werden, um etwas Spielraum zu schaffen, bis die Struktur geklärt ist.

Ihre Annahmen darüber, wie es verwendet wird, sind falsch

Unabhängig davon, wie gut etwas gestaltet ist, werden die Menschen einen Weg finden, etwas zu missbrauchen oder eine alternative Verwendung zu finden.

Eine Möglichkeit, dies zu handhaben, besteht darin, einen Großteil der Implementierung mithilfe von Zugriffsmechanismen (dh privat / öffentlich / intern) zu sperren, aber ohne viel Design oder Engineering erhalten Sie so viel Einsicht, wie Sie den Code an die Benutzer weitergeben.

Es ist wirklich egal, wie 'perfekt' Sie denken, dass Ihr Code werden kann. Ihre Benutzer werden beweisen, dass dies nicht der Fall ist.

Ich würde argumentieren, dass dies der Hauptgrund ist, warum es immer besser ist, eine vorhandene Codebasis zu verwenden, als eine vollständige Neuschreibung durchzuführen. Bestenfalls wird durch ein vollständiges Umschreiben das Aufblähen verringert, aber es besteht eine hohe Wahrscheinlichkeit, dass die neue Codebasis so viele (und möglicherweise mehr) Fehler enthält wie die ursprüngliche Codebasis.

In Ihrem Fall sind Sie von Grund auf kampferprobt, sodass Sie gleich loslegen können.


Es hört sich so an, als hättest du den Rest deiner Basen abgedeckt. API-Dokumentation ist von entscheidender Bedeutung und Tests sind gut, um die Stabilität sicherzustellen, wenn Änderungen in Zukunft vorgenommen werden.

Die Implementierung eines konsistenten Protokollierungsschemas ist wichtig, bevor der Code für die Produktion freigegeben wird, da Sie eine Möglichkeit zum globalen Aktivieren / Deaktivieren / Filtern der Protokolle benötigen. Übrigens: Bei der Protokollierung wird in den meisten Fällen nur eine Bibliothek importiert und die Ausgabeaufrufe von Debug.WriteLine () in Logging.Debug (), Logging.Info (), Logging.Error () geändert. Der Logger selbst bietet lediglich eine Standardimplementierung für die Konfiguration, Filterung und eine größere Auswahl an Ausgabeschemata (z. B. Dateien, Konsole usw.).

Ansonsten würde ich versuchen, den Code rauszuholen und ihn zu benutzen. Auch wenn nur von einer kleinen Anzahl von Benutzern zu starten.

Evan Scholle
quelle
1
+1 Re: Logging - Ich empfehle TraceSource . Es führt keine externen Abhängigkeiten ein, da es Teil der .NET-Kernbibliotheken ist und es Benutzern ermöglicht, Listener anzuhängen und die Ablaufverfolgung sowohl über Code als auch über app.config-Dateien zu konfigurieren.
Dan Lyons
4

Dies sind zwei Dinge, die ich für den Schlüssel zum Release von Software halte:

  • Wissen Sie genau, was Sie freigegeben haben
  • Verwalten Sie Ihre Erwartungen

Sie möchten in der Lage sein, zurück zu gehen und Fehler zu beheben, die Sie veröffentlicht haben, und Sie möchten, dass die Leute verstehen, welches Problem Ihr Code lösen wird.

Wissen, was Sie freigegeben haben

Stellen Sie sicher, dass Sie es korrekt versioniert und signiert haben (falls zutreffend). Verwenden Sie Ihre Quellcodeverwaltung, um den Code zu kennzeichnen, der der offiziell freigegebenen Version zugeordnet ist. Auf diese Weise können Sie Fehler leichter identifizieren, da Sie genau zu dem von Ihnen veröffentlichten Quellcode zurückkehren können. Es wird auch hilfreich sein, wenn Sie möglicherweise einige andere veröffentlichte Versionen haben.

Versuchen Sie, die neueste Version einfach zu finden und zu aktualisieren. Ob es sich um ein Installationsprogramm handelt oder ob Sie es einfach auf eine gemeinsame Freigabe stellen, hängt davon ab, wer \ wann \ wie oft Sie versenden.

Stellen Sie sicher, dass jemand Ihre endgültige Version einschließlich der Dokumentation überprüft. Es ist sehr leicht, nervös oder aufgeregt zu werden, Software zu veröffentlichen und etwas zu verpassen.

Erwartungen managen

Dokumentieren Sie die Einschränkungen und machen Sie sie den Entwicklern verständlich. Es ist gut, dass Sie sie gefunden haben. Die Leute sind oft verständnisvoller, wenn sie die Einschränkungen Ihrer Software kennen, insbesondere wenn Sie planen, sie zu beheben.

Dokumentieren Sie, wie Sie Feedback wünschen, ob gut oder schlecht. Wenn jeder Zugriff auf ein gemeinsames Fehlerverfolgungssystem hat, bitten Sie ihn, Fehler für das entsprechende Projekt zu melden, da es sich um ein internes Projekt handelt.

Vermeiden Sie in Zukunft, die API zu ändern, wenn dies möglich ist. Dies könnte Ihre Kunden verärgern. Denken Sie daran, dass Ausnahmen auch Teil der API sind, obwohl sie in C # nicht Teil der Methodendokumentation sind. Es kann möglich sein , die Ausnahmen verbessern zu einem späteren Zeitpunkt geworfen, aber Sie müssen für die Endbenutzer sprechen und sehen , welche Auswirkungen es haben wird.

Steve
quelle
0

Ich habe eine Checkliste für Bereitstellungen, die Sie möglicherweise nützlich finden. Ich mache Desktop-Entwicklung, aber einiges davon sollte übersetzt werden. Hier ist etwas davon:

Allgemeines:

  • Geben Sie null ein, um zu überprüfen, ob Funktionsparameter nicht null sein dürfen. Das hilft mir, früh zu scheitern.
  • Entfernen Sie unnötige Kommentare und auskommentierte Dateien. Diese verursachen zukünftige Arbeit.
  • Suchen Sie nach "// TODO" -Kommentaren. Manchmal hinterlasse ich mir Notizen. Manchmal vergesse ich sie.
  • Führen Sie nach Möglichkeit einen Test meines Codes in der Produktionsdatenbank durch. Auf diese Weise wird sichergestellt, dass alle meine Datenbankänderungen auf dem Produktionsserver gespeichert sind.
  • Führen Sie eine umfangreiche Protokollierung durch. Vor allem für einen ersten Einsatz. Tatsächlich speichere ich die Protokollierung für das Ende, da mein Code an dieser Stelle normalerweise etwas geliert ist. Sie möchten sich nicht in einer Situation befinden, in der Sie einen Absturz erleiden und sich selbst sagen: "Wenn ich nur wüsste, wie hoch der Wert von X zu diesem Zeitpunkt war". Versuchen Sie vorauszuplanen.
  • Versuchen Sie, Bibliotheksaufrufe von Drittanbietern in Facades einzubinden. Dies erleichtert das Ändern von Bibliotheken in der Zukunft und bietet eine Checkliste für die Anforderungen, die Sie an eine Bibliothek stellen.

.Net spezifisch:

  • Stellen Sie sicher, dass ich Dispose () für Einwegobjekte aufrufe. Ich benutze Code Analysis oder FxCop, um Fälle davon zu finden.
  • Stellen Sie sicher, dass ich alle Event-Handler ordnungsgemäß aushänge. Dies verhindert Speicherlecks.
user2023861
quelle