I know there is a huge debate about whether to annotate code.
I tend to agree with those that say the code should explain itself. However, at the same time, my ability to read code is not well-developed. Additionally, I am dyslexic, which challenges me further. One day, when I'm all growed up, I want to be one of those 'back to basics Bushcraft' programmers able to light fires with nothing more than a hex editor and a stick. Yet, so far, all I've got in my toolkit is a stick (two sticks, actually, cos I broke the first one).
I have created the three blocks in this project as a development aid. while there is already a facility to add comment ballons to blocks, I find that they can be knocked out of place and later discovered attached to the wrong block (would be nice if there were some way to lock them in place).
I think my blocks are strictly for development and education, for example, to communicate between pupil and teacher. I believe comments should be stripped out once the code is polished.
Agreed with @spielscratch! (except for the statement "comments should be stripped out once the code is polished" ... unless you meant: comments should be revisited and cleaned up).
Like @cymplecy I especially dig the third block, featuring both an introduction and an epilogue.
For what it's worth, here's a somewhat a similar block I recently created:
Update
Just now, inspired by @spielscratch, I expanded the "do"-block in my Programming tools library (see above) with an epilogue (or postscript) slot:
I like your do block!
My coding colleagues often tell me that well-meaning comments tend to stick around for years in code that has been refactored many times. Those once-useful comments then may be meaningless or perhaps even misleading. Uncle Bob once presented an entire lecture on commenting, it is on YoutTube somewhere.
i know in scratch those yellow block comments constantly get detached and moved around because of some bug, but i've never had issues with them in snap. they line up neatly with the rest of the code, and the risk of accidentally detaching them is about the same as accidentally detaching a block.
I've just scanned the Metaprogramming section, I'm still clueless as to how '"run" in the context of the caller' is achieved. Perhaps this is why good ideas require excellent engineering.
There is one downside to using a C-shape in a custom block: it complicates editing, and although that is solvable in principle, the Snap! development team chooses, for pedagogical reasons, to maintain the status quo (see the recent forum discussion on “C-shapes in custom blocks”).
So from an ease of use point of view, it may be wise not to overenthusiastically use c-shape custom blocks. Primitive blocks with C-shapes are easier to use (according to @bh this is a misfeature inherited from Scratch ). All things considered I may be going to use the (primitive) IF and IF … ELSE-blocks more often for encapsulating (alternative) groups of blocks, plus custom COMMENT-blocks (the equivalent of @spielscratch’s REMtile) for adding comments:
I made something like this once. It's basically like a function block but there's a built-in comment system. And you can choose to disable it or enable it.
, but you are ok, no problem. 
