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.