[Humjob]

Agreed. Annotated code with long-form explanations on the side (instead of annoying comments which clutter up the code itself) is a huge help to aiding my understanding. I hope one day that IDEs will incorporate a code commenting system with clickable 'overview comments' which expand into broader side bar descriptions, making the code shorter and more readable yet at the same time better documented.

[montanalow]

Which IDE do you use? We've been considering building extensions to common IDE's to allow teams to annotate code like this.