What are your preferences for referencing official documentation (like a white paper) for an algorithm from comments in
the code that implements it? I’m trying to decide between two methods, as illustrated by the examples below, but am
open to other suggestions. RFC 1321, for instance, describes the MD5 hash algorithm. If I were implementing MD5
in Python using the paper as a guide, and documented my code as I went, which of the following implementations of an
example function pad_string(str) would you recommend, if not something entirely different?
option 1
def pad_string(str):
"""
Pads the string to be hashed to an appropriate length. See RFC 1321 3.1.
"""
where the relevant section of the RFC is:
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.
or
option 2
def pad_string(str):
"""
Pads the argument string such that its length is congruent to 448, modulo 512.
"""
Here, option 1 simply references relevant parts of the “official” MD5 documentation by section number, where
option 2 doesn’t make any mention of the paper and basically reiterates its contents where necessary. The
advantage of the first is that the documentation adheres somewhat to DRY (Don’t Repeat Yourself, in this case with
respect to the RFC), but its disadvantage is that it relies on a third-party resource: if it’s an obscure technical
specification hosted in one place and the link provided inside the code documentation dies, then you’re out of luck.
The advantage of the second approach is that your source is self-contained: you don’t need any other information when
reading through it, and our example MD5 script would become as much a description of the algorithm as its
implementation; this, of course, requires more writing on the code author’s part, can bloat documentation, and, more
importantly, may end up with mis-copied information and other errors. Is there any consensus on which is better?
1
It depends on type of documentation. If it is a publicly facing function you probably should provide all information necessary to use API. For example if I want to use SMTP library to send an email I don’t want to read RFC 5321, RFC 2045, RFC 2046, RFC 2047, RFC 4288, RFC 4289, RFC 2049 and others as most parts are only vaguely relevant to what I want to achieve – in most cases I just want to send a simple message filling the To/From/Subject fileds and message – maybe add attachment if I feel adventurous. However you might want to reference it if RFC is simple and protocol is not well-known to provide additional information (or webpage describing protocol/format if it exists).
For internal documentation the more important is why rather then how (this part is covered by code) or what. Therefore referencing the specification is useful. It will also allow the person modified the code to see what (s)he can change or at least what part of spec (s)he needs to consider.
For example in your example it is probably clear from the code that pad_string pads string so result length is congruent to 448, modulo 512. However the MD5 spec provides reference why it is done.
Other method is to nearly copy and paste the paper/RFC into code if flow is non-trivial and you cannot avoid it by making the code nicer in one way or another. For example lets say the pseudocode is:
Ri <- head from stack
Merge Ri and Rj
if Ri' is not well balanced then
balance(Ri')
push Ri' on stack
You can do something like:
// 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')
...
Also, of course, in such case you need to check the copyright law first (this is not a legal advice that it is permitted, especially that copyright law vary from jurisdiction to jurisdiction).