Warum ich das jetzt schreiben muss, kann ich kaum glauben – aber offenbar ist es notwendig!
Wenn Sie diesen Artikel lesen, sind Sie sehr wahrscheinlich auch Software-Entwickler. Was erwarten Sie von einem Drittanbieter-Framework? Das es funktioniert? Klar, was noch?
Was ich von einem Framework/API erwarte
Dass ein Framework machen soll wofür es konzipiert ist, brauchen wir wohl nicht zu diskutieren. Darum möchte ich jetzt über einen Aspekt schreiben, der so einigen Framework-Entwicklern wohl nicht geläufig ist. Die Rede ist von der Dokumentation.
Was ist eine Dokumentation?
Blöde Frage? Offenbar nicht! Für mich besteht die Dokumentation aus folgenden Teilen:
- Ein Guide als normaler Text (PDF, Word-Dokument, etc)
- Codesamples / Tutorials
- Schnellreferenz im CHM-Format
- XML-Kommentare für alle öffentlichen Member
Ein Guide
Dieses Dokument erklärt, was man mit dem Framework überhaupt machen kann. Begleitet wird es von…
Codesamples / Tutorials
Ich erwarte dass er dieses Dokument mit aussagekräftigen Codesamples ausstattet! Ein paar erklärende Worte dazu erwarte ich ebenfalls!
Schnellreferenz im CHM-Format
Die MSDN Library dürfte wohl die Anlaufstelle Nr. 1 für jeden .Net-Entwickler sein. Die ist doch toll gemacht, oder? Wenn Sie nichts von Dokumentation halten, regen Sie sich bestimmt nicht über ein paar fehlende Samples auf, oder doch? Dann fassen sie sich jetzt mal an Ihre Nase!
Wissen Sie dass Sie für Ihr Framework Hilfsdokumente in dem gleichen Format herstellen können? Ja? Warum machen sie es dann nicht?! Falls Sie es wirklich nicht wissen, schauen sie sich einmal SandCastle und den SandCastle HelpFileBuilder an.
Warum ich dieses Dokument erwarte? Warum besuchen Sie die MSDN-Library? Beantworten Sie sich selbst diese Frage und Sie wissen warum.
Falls Ihr Guide aber schon eine komplette Schnellreferenz enthält, können Sie sich das CHM File natürlich sparen.
XML-Kommentare für alle öffentlichen Member
IntelliSense in Visual Studio ist eine tolle Sache was? Fügen Sie den öffentlichen Membern Ihres Frameworks XML-Kommentare hinzu, damit ihr Framework IntelliSense anbietet! Es ist nicht schwer, es macht nur mehr Arbeit, das gebe ich zu. Sie sind doch stolz auf das was sie geschaffen haben – so stolz dass sie es veröffentlichen und sich wünschen dass andere Entwickler mit Ihrem Framework arbeiten. Sollte Ihnen das nicht den Mehraufwand wert sein?
Übrigens: Wenn Sie XML-Kommentare schreiben, ist das CHM-Dokument schon so gut wie fertig! Zwei Fliegen mit einer Klappe! Der SandCastle HelpfileBuilder braucht nämlich genau diese für die Generierung des CHM-Dokuments. Nur noch ein paar Metainformationen eintragen, auf den Build-Button klicken und Sie können sich genüsslich zurücklehnen.