Code Comments

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.

This post was flagged by the community and is temporarily hidden.

Yes - these type of comment blocks are quite useful :slight_smile:

I'd not thought of using the last example before - nice idea :slight_smile:

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:

Programming tools script pic (2)

For details, see: Snap! Programming tools (berkeley.edu)

Update
Just now, inspired by @spielscratch, I expanded the "do"-block in my Programming tools library (see above) with an epilogue (or postscript) slot:

Programming tools script pic (4)

I think the C-blocks should run the code inside of them like this

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.

Good point; I missed that.

I put in comments to remind my self next week what I thought my code should be doing :slight_smile:

I've updated my code following your example.

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.

You introduced sub-scope this way
untitled script pic (1)
Also
untitled script pic (2)
does not report anything.

Macro capabilities should be used to "run" in the context of the caller.
XI. Metaprogramming (.105) @ Snap Reference Manual

I think the risk of accidentally detaching them is proportional to the level of Butterfinger.

Thank you dardoro,

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.

Why is this flagged?I think that this shoulf moove to #show-projects

You have reason, because #show-projects is to show the projects of users.
I don't know why the people flagged you :face_with_monocle:, but you are ok, no problem. :slightly_smiling_face:

You are kind

You just said

With no context whatsoever. That's why it was flagged.

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 :slight_smile: ). 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:

Programming tools script pic 4

I just noticed my comment has a typo 'cooment' instead of 'comment'. Oh dyslexia, you try me at times!

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.

It's useful for debugging.