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
