On 28 December 2012 11:27, Amit Kapila <amit.kap...@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 -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
