On 28 December 2012 11:27, Amit Kapila <amit.kapila@huawei.com> wrote:
>> * The internal docs are completely absent. We need at least a whole
>> page of descriptive comment, discussing trade-offs and design
>> decisions. This is very important because it will help locate bugs
>> much faster if these things are clealry documented. It also helps
>> reviewers. This is a big timewaster for committers because you have to
>> read the whole patch and understand it before you can attempt to form
>> opinions. Commits happen quicker and easier with good comments.
>
> Do you have any suggestion for where to put this information, any particular
> ReadMe?
Location is less relevant, since it will show up as additions in the patch.
Put it wherever makes most sense in comparison to existing related
comments/README. I have no preference myself.
If its any consolation, I notice a common issue with patches is lack
of *explanatory* comments, as opposed to line by line comments. So
same review comment to 50-75% of patches I've reviewed recently, which
is also likely why.
-- Simon Riggs http://www.2ndQuadrant.com/PostgreSQL Development, 24x7 Support, Training & Services