Thoughts to keep in mind for Code Review

[Jeroen Vermeulen]

On 2014-06-25 09:43, roger peppe wrote:

> About pre-review annotations, I agree with Ian that the code should be
> documented
> well enough that someone coming to it from scratch can understand it, but
> I also wonder if there is a room for review-specific comments, talking about
> reasons for the changes themselves in the specific context of that review.

There is, I think.  But should it be quite so close to the code, where 
it competes against commenting for the coder's time?

Don't know if there's a definite answer, because either way we assume a 
human process to complement the technical solution.  But if a coder 
starts by reviewing their own code, perhaps they should also turn these 
notes into a single coherent "cover letter" and, in explaining, perhaps 
spot structural flaws or anticipate questions.


Jeroen