On Sep 18, 2006, at 11:17 AM, Paul McMahan wrote:
I agree that readability is a huge factor in code quality and is a key to its survival. But I tend to disagree that a commit should be rejected based on this criteria alone. IMHO the low bar for committing to trunk should be that it compiles, does no harm, and has undergone adequate discussion within the dev community.
I also agree it shouldn't be a gate to committing the code. But for the person who is looking at the code six months from now it might be nice to have part of that discussion on the dev list condensed into the code in the form of a comment. At least that way people wouldn't be forced to mine for information about a module through Google.
I also think rules in this area will be impossible to enforce and will slow things down. If there has to be discussion about something in e-mail from a commit then perhaps that is an indication that the code wasn't clear to begin with and might need a bit of clarification.
Providing adequate comments lies just outside that threshold as something that you should expect to be nagged heavily about but not necessarily vetoed. Like you say, in most cases this will be resolved through simple discussion. Best wishes, Paul
