api-Dokumentation und „Wertgrenzen“: tun sie überein?

Question

Sehen Sie oft in der API-Dokumentation (wie in ‚javadoc öffentlichen Aufgaben‘ zum Beispiel) die Beschreibung von „Wertgrenzen“ sowie die klassischen Dokumentation?

Hinweis: Ich spreche nicht über Kommentare im Code

Mit dem "Wertgrenze", meine ich:

• ist ein Parameter einen Nullwert unterstützen (oder einen leeren String, oder ...)?
• hat ein ‚Rückgabewert‘ Null sein kann oder ist garantiert nie null sein (oder „leer“ oder ... sein)?

Beispiel:

Was ich sehe oft (ohne Zugriff auf den Quellcode zu haben) ist:

/**
 * Get all readers name for this current Report. <br />
 * <b>Warning</b>The Report must have been published first.
 * @param aReaderNameRegexp filter in order to return only reader matching the regexp
 * @return array of reader names
 */
 String[] getReaderNames(final String aReaderNameRegexp);

Was I wie sehen wäre:

/**
 * Get all readers name for this current Report. <br />
 * <b>Warning</b>The Report must have been published first.
 * @param aReaderNameRegexp filter in order to return only reader matching the regexp 
 * (can be null or empty)
 * @return array of reader names 
 * (null if Report has not yet been published, 
 *  empty array if no reader match criteria, 
 *  reader names array matching regexp, or all readers if regexp is null or empty)
 */
 String[] getReaderNames(final String aReaderNameRegexp);

Mein Punkt ist:

Wenn ich eine Bibliothek mit einer getReaderNames () Funktion in es verwende, habe ich oft brauche nicht einmal die API-Dokumentation zu lesen, zu erraten, was es tut. Aber ich muss sicher sein wie es zu benutzen .

Meine einzige Sorge, wenn ich will diese Funktion nutzen ist: Was soll ich erwarten, dass Werte in der Bezeichnung der Parameter und zurück? Das ist alles was ich brauche, um sicher meine Setup-Parameter kennen und sicher den Rückgabewert testen, aber ich fast nie diese Art von Informationen in der API-Dokumentation sehen ...

Edit:

Dies kann die Nutzung beeinflussen oder nicht für aktiviert oder deaktiviert Ausnahmen .

Was denken Sie? Wertgrenzen und API, gehören sie zusammen oder nicht?

Answer 1

Ich denke, sie können gehören zusammen, aber nicht notwendigerweise Haben zusammen gehören. In Ihrem Szenario, wie es scheint, ist es sinnvoll, dass die Grenzen so dokumentiert werden, dass sie in der generierten API-Dokumentation und Intellisense angezeigt (wenn die Sprache / IDE-Unterstützung it).

Ich denke, es ist auch von der Sprache abhängt. Zum Beispiel hat Ada einen native Datentyp, der ein „eingeschränkten integer“ ist, in dem Sie ein Integer-Variable definieren und explizit angeben, dass es nur (und immer) innerhalb eines bestimmten numerischen Bereichs sein. In diesem Fall zeigt sich der Datentyp der Beschränkung. Es sollte noch sichtbar und auffindbar durch die API-Dokumentation und intellisense sein, wäre aber nicht etwas, das ein Entwickler in den Kommentaren geben hat.

Allerdings Sprachen wie Java und C # nicht über diese Art von eingeschränkten integer, so würde der Entwickler hat es in den Kommentaren an, ob es Informationen waren, der Teil der öffentlichen Dokumentation werden soll.

Answer 2

Ich denke, diese Art von Randbedingungen auf jeden Fall in der API gehört. Allerdings würde ich (und oft tun) gehen noch einen Schritt weiter und zeigen, was diese Nullwerte bedeuten. Entweder ich deute es wird eine Ausnahme werfen, oder ich erklären, was die erwarteten Ergebnisse sind, wenn der Grenzwert in geben wird.

Es ist schwer, sich daran zu erinnern, dies zu immer tun, aber es ist eine gute Sache für die Benutzer Ihrer Klasse. Es ist auch schwierig, sie zu halten, wenn der Vertrag das Verfahren Änderungen präsentiert (wie Nullwerte nicht erlaubt werden, geändert werden) ... Sie haben auch fleißig die Dokumentation zu aktualisieren, wenn Sie die Semantik der Methode ändern.

Answer 3

Frage 1

  

Sehen Sie oft in der API-Dokumentation (wie in ‚javadoc öffentlichen Aufgaben‘ zum Beispiel) die Beschreibung von „Wertgrenzen“ sowie die klassischen Dokumentation?

Fast nie.

Frage 2

  

Meine einzige Sorge, wenn ich will diese Funktion nutzen ist: Was soll ich erwarten, dass Werte in der Bezeichnung der Parameter und zurück? Das ist alles was ich brauche, um sicher meine Setup-Parameter kennen und sicher den Rückgabewert testen, aber ich fast nie diese Art von Informationen in der API-Dokumentation sehen ...

Wenn ich eine Funktion nicht richtig verwendet wird, würde ich ein RuntimeException erwarten durch das Verfahren geworfen oder ein RuntimeException in einer anderen (manchmal sehr weit) Teil des Programms.

Kommentare wie @param aReaderNameRegexp filter in order to ... (can be null or empty) scheint mir eine Art und Weise Design by Contract zu implementieren in einer menschlichen Befinden Sprache innerhalb Javadoc .

Javadoc Mit Design by Contract zur Durchsetzung von iContract verwendet wurde, wieder belebt jetzt in JcontractS , dass können Sie angeben, Invarianten, Voraussetzungen, Nachbedingungen , in formalisierte Weise im Vergleich zur menschlichen Befinden Sprache.

Frage 3

  

Dies kann die Nutzung beeinflussen oder nicht aktiviert oder deaktiviert Ausnahmen.   Was denkst du ? Wertgrenzen und API, gehören sie zusammen oder nicht?

Java-Sprache hat kein Design by Contract-Funktion, so dass Sie Execption zu verwenden versucht sein könnten, aber ich stimme mit Ihnen über die Tatsache, dass Sie sich bewusst sein müssen: wenn diese Option aktiviert und ungehemmt Ausnahmen wählen. Wahrscheinlich könnten Sie nicht markiert IllegalArgumentException, IllegalStateException verwenden, oder Sie können Unit-Tests verwenden, aber das größte Problem ist, wie man andere Programmierer zu kommunizieren, dass ein solcher Code ist über Design by Contract und sollte als ein Vertrag in Betracht gezogen werden, bevor es zu leicht zu ändern.

Answer 4

Ich denke, sie tun, und haben immer Kommentare in den Header-Dateien (c ++) platziert arcordingly.

Neben gültige Eingabe / Ausgabe / Return-Kommentare, stelle ich fest, auch die Ausnahmen sind likly durch die Funktion geworfen werden (da ich oft für den Rückgabewert verwenden wollen ... na ja einen Wert zurück, ziehe ich es Ausnahmen über Fehlercodes)

//File:
// Should be a path to the teexture file to load, if it is not a full path (eg "c:\example.png") it will attempt to find the file usign the paths provided by the DataSearchPath list
//Return: The pointer to a Texture instance is returned, in the event of an error, an exception is thrown. When you are finished with the texture you chould call the Free() method.
//Exceptions:
//except::FileNotFound
//except::InvalidFile
//except::InvalidParams
//except::CreationFailed
Texture *GetTexture(const std::string &File);

Answer 5

@fire Lancer: Richtig! Ich vergaß Ausnahme, aber ich mag sie erwähnt, vor allem die nicht markiert ‚Laufzeit‘ Ausnahme sehen, dass diese öffentliche Methode werfen könnte

@ Mike Stone:

  

Sie müssen fleißig sein auch die Dokumentation zu aktualisieren, wenn Sie die Semantik der Methode ändern.

Mmmm Ich hoffe sicher, dass die öffentliche API-Dokumentation ist zumindest aktualisiert, wenn eine Änderung -, die den Vertrag der Funktion beeinflusst - stattfindet. Wenn nicht, könnten diese API-Dokumentationen zusammen fallen werden.

Um Lebensmittel zu verkaufen Gedanken hinzufügen (und gehen mit @ Scott Dorman), stolpere ich nur auf die Zukunft der Java7 Anmerkungen

Was bedeutet das? Daß gewisse ‚Randbedingungen‘, eher als in der Dokumentation zu sein, sollte sich in der API besser dran, und automatisch verwendet, bei der Kompilierung mit entsprechenden ‚behaupten‘ generierten Code.

So, wenn ein ‚@CheckForNull‘ in der API ist, kann der Verfasser der Funktion weg mit nicht einmal zu dokumentieren! Und wenn die semantische Änderung, wird seine API diese Änderung widerspiegeln (wie ‚nicht mehr @CheckForNull‘ zum Beispiel)

Diese Art von Ansatz schlägt vor, dass die Dokumentation, für ‚Randbedingungen‘, ist ein zusätzlicher Bonus statt einer obligatorischen Praxis.

Allerdings ist das nicht die besonderen Werte des Rückgabeobjekt einer Funktion abzudecken. Dafür ein vollständig Dokumentation ist nach wie vor erforderlich.