<div dir="ltr"><div class="gmail_extra">Hi!</div><div class="gmail_extra"><br><div class="gmail_quote">On Thu, Apr 28, 2016 at 8:16 AM, Richard A. O'Keefe <span dir="ltr"><<a href="mailto:ok@cs.otago.ac.nz" target="_blank">ok@cs.otago.ac.nz</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div>I'm hoping that comparatively lightweight annotations that could be<br>
exploited by an IDE (at least in principle) are something programmers<br>
might be willing to use.  Even me!</div></blockquote></div><br>What kind of annotations do you have in mind?</div><div class="gmail_extra"><br></div><div class="gmail_extra">For me, there are two main kinds of code complexity that need explanations: static and dynamic. </div><div class="gmail_extra"><br></div><div class="gmail_extra">The static one refers to the way functions call each other and can be mitigated by using small functions that do just one thing and by naming them in a meaningful way. Then a cross-referencing tool can connect the dots and produce a useful description of the structure. Annotations could help even further by providing a bit of "why"-knowledge. My feeling is that the same reason that makes naming functions difficult might make writing useful annotations just as difficult. </div><div class="gmail_extra"><br></div><div class="gmail_extra">The dynamic complexity is harder to tame, though. It's about run-time interactions that are best described by message diagrams, protocol descriptions and the like. (Often, the interactions are inter-modular too, but maybe this is not the meso-level you want to document?) I can't see what kind of annotations in the code would help here, except in toy-level examples. For me, this is the part that is usually most difficult to understand when reading code. </div><div class="gmail_extra"><br></div><div class="gmail_extra">best regards,</div><div class="gmail_extra">Vlad</div><div class="gmail_extra"><br></div></div>