Thank you for your time in responding to my question; at our company, we believe in heavily documenting all code before it can be accepted (if that means that people need to work late to get it in, they do ^_^). One of the things that we've found is that what is easy and obvious today is crazy and esoteric tomorrow (especially when it's someone else reading the code).
True, this may be a 25-line function, but it's a 25-line function about 25-function-calls into a strange library whose internals I truly have no need or reason to learn or understand (my company uses SNMP to *monitor* data; we do not tweak the library or do any work with it unless we find a problem with it). The fix was conceptually easy, but at the same time, where it was located was hard to find and hard to understand for someone new to the code. Aside: we had once outsourced something to a company who claimed that its code was so good that it essentially was its own documentation (i.e., there were little to no comments). The code itself was fairly easy to follow, but the *intention* behind the code was entirely non-existent. We ended up just scrapping their work and rewriting it from scratch. The point being is that comments usually capture a bit of the intention behind the code; anyone can read valid C (except for some crazy constructs; you know what I mean), but trying to figure out *why* we're checking for less-than-or-equal-to-zero in a particular case is sometimes more important than actually checking for it. By knowing why something was done, one can go deeper both into the code and into understanding it and make greater improvements that would not be possible with just the code itself. I don't mean to criticize anyone in particular; I was hoping that we could collectively make a push for a more coder-friendly source code that newbies can read. Thanks again, Doug On Sun, May 23, 2010 at 6:25 PM, Dave Shield <d.t.shi...@liverpool.ac.uk> wrote: > On 22 May 2010 00:04, Doug Manley <doug.man...@gmail.com> wrote: >> 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. > > As the person who applied that particular patch, I should perhaps > say a few words here. > > Firstly, I would definitely agree that documentation (both comments > within the code, and external standalone descriptions) is one of the > major weaknesses of the project. There is certainly no general policy > of deliberately stripping comments from submitted patches. > > However, looking again at the patch in question, it effectively involved > a one-line change to one relatively short routine (snmp_fix_pdu). > This routine is about 25 lines long, and already had a significant > comment block at the head, describing the behaviour of that code. > > My judgement at the time (right or wrong) was that most of the > new comments in the patch were simply duplicating descriptions > that were already present. > I therefore decided to keep the documentation in line with the > existing code, and added mention of the new test into that comment > block. This also kept the size of the revision relatively small > (three lines changed rather than a dozen or so) > > > Looking at the patch again, in the light of this conversation, > I'd probably say that there is some useful information which > was not already covered. For omitting that, I can only apologise. > > But I would also stand by my original judgement that there was > no benefit in adding in-line comments for each individual test, > given the descriptive block immediately above. > > >> 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. > > I can categorically assure you that there is no sense of trying to > "control knowledge" about the code. Both providing support > for this project, and my (depressingly rare) attempts to provide > new or improved functionality - all has to be fitted into spare time > around my main work and home commitments. So anything > that improves general understanding (and hopefully reduces the > number of questions) is definitely A Good Thing. > > And I'm sure the other core developers would have a similar view. > > > >> 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. > > I would agree 100% with that. > > The only "huge issue" is probably the age-old one of time (or lack of it). > While I certainly try to comment the code that I write, (and have spent > the last twenty years trying to drum the importance of this into our > students), it's not always easy to judge the best level of description. > And sometime we get sloppy, and commit undercommented code. > > The problem then is finding the time to go back and properly document > code that is inadequately covered. If it's a choice between doing that, > fixing problems that people have reported, tackling misunderstandings > on the lists, or extending functionality - documentation tends to lose out. > I wouldn't suggest that this is right, but it's human nature. > > > Anyway, I hope that explains something of why the patch was > handled in the way that it was. And even if you don't agree with > the decisions that I made, you can at least understand something > of the reasoning behind them. > > Dave > ------------------------------------------------------------------------------ _______________________________________________ Net-snmp-coders mailing list Net-snmp-coders@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/net-snmp-coders
