Riferimenti alla documentazione ufficiale nella documentazione del codice sorgente

Question

Riferimenti alla documentazione ufficiale nella documentazione del codice sorgente

#1 da (1 voti)

1

Quali sono le tue preferenze per referenziare la documentazione ufficiale (come un white paper) per un algoritmo dai commenti in il codice che lo implementa? Sto cercando di decidere tra due metodi, come illustrato dagli esempi di seguito, ma sono aperto ad altri suggerimenti. RFC 1321 , ad esempio, descrive l'algoritmo di hash MD5. Se stavo implementando MD5 in Python usando la carta come guida e documentato il mio codice mentre procedevo, quale delle seguenti implementazioni di a la funzione di esempio pad_string(str) ti consiglierebbe, se non qualcosa di completamente diverso?

opzione 1

def pad_string(str):
    """
    Pads the string to be hashed to an appropriate length. See RFC 1321 3.1.
    """

dove la sezione pertinente della RFC è:

3.1 Step 1. Append Padding Bits

    The message is "padded" (extended) so that its length (in bits) is
    congruent to 448, modulo 512. That is, the message is extended so
    that it is just 64 bits shy of being a multiple of 512 bits long.
    Padding is always performed, even if the length of the message is
    already congruent to 448, modulo 512.

o

opzione 2

def pad_string(str):
    """
    Pads the argument string such that its length is congruent to 448, modulo 512.
    """

Qui, l'opzione 1 fa semplicemente riferimento a parti rilevanti della documentazione MD5 "ufficiale" per numero di sezione, dove L'opzione 2 non fa alcuna menzione del documento e, sostanzialmente, ne reiterà il contenuto laddove necessario. Il Il vantaggio del primo è che la documentazione aderisce in qualche modo a DRY (non ripetere te stesso, in questo caso con rispetto al RFC), ma il suo svantaggio è che si basa su una risorsa di terze parti: se è un oscuro tecnico specifica ospitata in un posto e il link fornito all'interno della documentazione del codice muore, quindi sei fuori di fortuna. Il vantaggio del secondo approccio è che la tua fonte è autonoma: non hai bisogno di altre informazioni quando leggendolo, e il nostro esempio di script MD5 diventerebbe tanto una descrizione dell'algoritmo quanto suo implementazione; questo, ovviamente, richiede più scrittura sul codice dell'autore, può ingigantire la documentazione, e altro ancora importante, potrebbe finire con informazioni copiate male e altri errori. C'è un consenso su quale sia il migliore?

documentation

posta Severyn Kozak 09.07.2014 - 01:18

fonte

1 risposta

Leggi altre domande sui tag documentation

Algoritmo per "de-rasterizzare" un'immagine voxel di un poliedro Permessi per app a pagina singola rappresentati tramite API RESTful

score 1 · Accepted Answer

Dipende dal tipo di documentazione. Se si tratta di una funzione rivolta pubblicamente, probabilmente dovresti fornire tutte le informazioni necessarie per utilizzare l'API. Ad esempio, se desidero utilizzare la libreria SMTP per inviare un messaggio di posta elettronica, non desidero leggere RFC 5321, RFC 2045, RFC 2046, RFC 2047, RFC 4288, RFC 4289, RFC 2049 e altri poiché la maggior parte delle parti è solo vagamente rilevante per quello che voglio ottenere - nella maggior parte dei casi, voglio solo inviare un semplice messaggio che riempie i campi e il messaggio di To / From / Subject - magari aggiungere un allegato se mi sento avventuroso. Tuttavia, si potrebbe fare riferimento ad esso se RFC è semplice e il protocollo non è noto per fornire ulteriori informazioni (o pagina web che descrive il protocollo / formato se esiste).

Per la documentazione interna, il più importante è il motivo per cui piuttosto allora come (questa parte è coperta dal codice) o cosa. Pertanto, fare riferimento alla specifica è utile. Permetterà inoltre alla persona che ha modificato il codice di vedere che cosa può cambiare o almeno quale parte delle specifiche deve essere presa in considerazione.

Ad esempio nel tuo esempio è probabilmente chiaro dal codice che pad_string blocca la stringa in modo che la lunghezza del risultato sia congruente a 448, modulo 512. Tuttavia la specifica MD5 fornisce un riferimento perché è stata eseguita.

Un altro metodo è quasi copiare e incollare la carta / RFC nel codice se il flusso non è banale e non puoi evitarlo rendendo il codice più bello in un modo o nell'altro. Ad esempio, diciamo che lo pseudocodice è:

Ri <- head from stack
Merge Ri and Rj
if Ri' is not well balanced then
   balance(Ri')
push Ri' on stack

Puoi fare qualcosa come:

// Ri <- head from stack
Node *Ri = stack_pop(stack);
// Merge Ri and Rj
Node *Rj = NULL;
while(!empty(Ri) && !empty(Rj)) {
   Node *next;
   if (foo(peek(Ri), peek(Rj))) {
       next = get(Ri);
   } else {
       next = get(Rj);
   }
   add(Rj, next);
}
// if Ri' is not well balanced then
//   balance(Ri')
...

Inoltre, ovviamente, in tal caso è necessario prima controllare la legge sul copyright (questo non è un parere legale che è permesso, in particolare che la legge sul copyright varia da giurisdizione a giurisdizione).