On Tue, Oct 05, 2004 at 08:18:50AM +0200, Shachar Shemesh wrote: > Such comments do suffer from another problem. They tend to fall out of > date. For that reason alone I'm not sure this comment is a good idea. > Otherwise, we get a future commit that changes something, but neglects > to update the comment accordingly, and the comment turns useless or even > dangerous. Maybe if we change that to contain the date or the CVS > version number of the file that was audited....
This is not a problem for these comments because: -- each control is implemented in one, and only one file -- each control has it's own independent audit -- the comment is at the top of the file, where it's most visible -- from the previous 3 points, it's very difficult to work on any control without stumbling upon it. -- it includes the exact version of the documentation, so when new documentation is released, we can compute the delta -- it includes the exact date when the audit took place, so we can compute deltas on the control side -- they are not open ended. That is, they list all the missing features, and such, if people forget to update them, 99% of the time this simply means they forgot to *delete* something. This is much less of a problem then not adding. It can easily get fixed when someone does a new audit, or wants to reimplement that feature. -- we had them for more then 2 years now, and there wasn't a single instance when people forgot to update them. Which means that the theory detailed this far actually works in practice. -- I've been closely watching patches againt controls myself (along with a few other people, it seems), so we have a pretty good safety net. -- Dimi.