Devo usare RFC 2119 nella documentazione dell'interfaccia?

1

RFC 2119 definisce diversi termini, tra cui MUST, DOVREBBE e MAY, per l'uso in documenti standard, in particolare quelli relativi a protocolli di rete come IP e HTTP. Questi termini sono ampiamente utilizzati nelle RFC per descrivere il livello di requisiti dei singoli articoli in una specifica (ad esempio "il server DEVE fare X" o "il cliente PU do fare Y").

È una buona idea documentare i requisiti di un'interfaccia usando RFC 2119? Ad esempio, un'interfaccia simile a un file potrebbe dire questo:

The .close() method SHOULD be called prior to program termination. After calling the .close() method, other methods in this interface MUST NOT be called.

(Queste affermazioni sembrano ovvie, ma non tutte le interfacce sono così generiche. Un'interfaccia per scopi speciali potrebbe avere vincoli più interessanti.)

Mi piacciono questi termini perché forniscono una descrizione non ambigua ma concisa di ciò che richiede l'interfaccia, di ciò che raccomanda e di ciò che consente, senza entrare nei dettagli dell'implementazione, e possono essere usati per vincolare sia l'implementazione che il codice cliente . Ma immagino che sembrino piuttosto strani a persone che non hanno familiarità con loro, anche se includo lo standard "questo documento usa il blocco di testo RFC 2119".

    
posta Kevin 14.04.2016 - 19:27
fonte

0 risposte

Leggi altre domande sui tag