What are your preferences for referencing official documentation (like a white paper) for an algorithm from comments inthe code that implements it? I'm trying to decide between two methods, as illustrated by the examples below, but amopen to other suggestions. RFC 1321, for instance, describes the MD5 hash algorithm. If I were implementing MD5in Python using the paper as a guide, and documented my code as I went, which of the following implementations of anexample function pad_string(str) would you recommend, if not something entirely different?option 1def 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.oroption 2def 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, whereoption 2 doesn't make any mention of the paper and basically reiterates its contents where necessary. Theadvantage of the first is that the documentation adheres somewhat to DRY (Don't Repeat Yourself, in this case withrespect to the RFC), but its disadvantage is that it relies on a third-party resource: if it's an obscure technicalspecification 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 whenreading through it, and our example MD5 script would become as much a description of the algorithm as itsimplementation; this, of course, requires more writing on the code author's part, can bloat documentation, and, moreimportantly, may end up with mis-copied information and other errors. Is there any consensus on which is better?
Referencing official documentation in source-code documentation
documentation
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 stackMerge Ri and Rjif Ri' is not well balanced then   balance(Ri')push Ri' on stackYou can do something like:// Ri <- head from stackNode *Ri = stack_pop(stack);// Merge Ri and RjNode *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). 