Oh, this explains why I was forced to spend days (elapsed time weeks) understanding the Net-SNMP agent code, which I need to modify in order to implement an audit log feature.
AARRRGGGGHHHHH!!!!!! A while ago, I posted to the Net-SNMP users mailing list a question about a guide to the source code, or a design document, which explains the higher level organization of the code and its flow of control. No one answered me. Now I am flabbergasted that anything leading toward such documentation has been censored from Net-SNMP commits. Contrast this policy with the Linux kernel one of retaining comments and even having a Documentation subdirectory. --- Omer On Fri, 2010-05-21 at 19:04 -0400, Doug Manley wrote: > Hi, team! > > I've submitted numerous patches to the net-snmp project for errors so > esoteric that it took days to find and understand them. > > In my painful searches through the commentless code, I built up an > understanding of the necessary components and added in many comments > to help steer people in the right direction, save them hours of time, > and help everyone extend the code. > > I recently realized that a patch that I submitted a year or two ago > had been stripped of all of its comments (and thus a good deal of its > usefulness). Granted, my fix (to prevent infinite looping) was kept, > but all of the knowledge and reasoning behind that fix was stripped. > > Here's a piece the original patch: > @@ -590,10 +591,24 @@ > { > netsnmp_pdu *newpdu; > > - if ((pdu->command != SNMP_MSG_RESPONSE) > + if ( > + // We're only going to fix a PDU if it was a *response* to us. > + (pdu->command != SNMP_MSG_RESPONSE) > + // We're only going to fix a PDU that had an error. > || (pdu->errstat == SNMP_ERR_NOERROR) > + // We're only going to fix a PDU that has varbinds. > || (0 == pdu->variables) > - || (pdu->errindex <= 0)) { > + // We're only going to fix a PDU with a positive error-index. > + || (pdu->errindex <= 0) > + // We're only going to fix a PDU if we can actually remove > + // the varbind that was listed as being "bad". If the number > + // of varbinds is *less* than the error-index value, then > + // we can't really do anything except simply resend the PDU > + // and hope for a better response, and that's not a good > + // thing to do; previously, this had led to infinite loops > + // of send, receive, and resend. > + || (pdu->errindex > snmp_varbind_len(pdu)) > + ) { > return 0; /* pre-condition tests fail */ > } > > You'll note that most of the "+" signs are comments. To someone who's > trying to find the cause of a problem, these are gold; to that person, > these variables and conditions have no meaning. If you haven't worked > in the code for long periods of time, a lot of the "obvious" things > that snmp-gurus might know are completely new and foreign to the rest > of us. > > Maybe someone was against the C++-style comments ("//" comments); > however, C99 has included them in the C language (see section 6.4.9, > "Comments", item #2). > > In any case, I've seen this kind of behavior in many open-source > projects, and it only hurts the project. If we cannot justify (to our > readers, to our developers, to our helpers in the open-source > community), then we're back to square one of trying to control the > knowledge about the code. > > Unless there is some huge issue of which I am unaware, I strongly > suggest that everyone fully comment his code; justify its existence, > and make note of its shortcomings. In the end, we all benefit. > > Thank you for your time, > Doug -- In civilized societies, captions are as important in movies as soundtracks, professional photography and expert editing. My own blog is at http://www.zak.co.il/tddpirate/ My opinions, as expressed in this E-mail message, are mine alone. They do not represent the official policy of any organization with which I may be affiliated in any way. WARNING TO SPAMMERS: at http://www.zak.co.il/spamwarning.html ------------------------------------------------------------------------------ _______________________________________________ Net-snmp-coders mailing list Net-snmp-coders@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/net-snmp-coders