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
pad_string(str) would you recommend, if not something entirely different?
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.
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?