<div dir="ltr">I agree that the code needs to be self-explanatory enough to not require annotations, but annotations can be useful - especially for larger changes. Suggesting the order for code to be reviewed is certainly useful if you're reviewing code in a part of the system you aren't familiar with</div>

<div class="gmail_extra"><br><br><div class="gmail_quote">On Wed, Jun 25, 2014 at 10:25 AM, Jeroen Vermeulen <span dir="ltr"><<a href="mailto:jeroen.vermeulen@canonical.com" target="_blank">jeroen.vermeulen@canonical.com</a>></span> wrote:<br>

<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="">On 2014-06-25 09:43, roger peppe wrote:<br>
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
About pre-review annotations, I agree with Ian that the code should be<br>
documented<br>
well enough that someone coming to it from scratch can understand it, but<br>
I also wonder if there is a room for review-specific comments, talking about<br>
reasons for the changes themselves in the specific context of that review.<br>
</blockquote>
<br></div>
There is, I think.  But should it be quite so close to the code, where it competes against commenting for the coder's time?<br>
<br>
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.<span class="HOEnZb"><font color="#888888"><br>


<br>
<br>
Jeroen</font></span><div class="HOEnZb"><div class="h5"><br>
<br>
-- <br>
Juju-dev mailing list<br>
<a href="mailto:Juju-dev@lists.ubuntu.com" target="_blank">Juju-dev@lists.ubuntu.com</a><br>
Modify settings or unsubscribe at: <a href="https://lists.ubuntu.com/mailman/listinfo/juju-dev" target="_blank">https://lists.ubuntu.com/<u></u>mailman/listinfo/juju-dev</a><br>
</div></div></blockquote></div><br></div>