Comment block pack & Block (pack) requests

Comment block pack

The description is in the project.

Block (pack) requests

Individual blocks

Block name: Block help: Function and/or Purpose:

Block pack

Pack name: Pack description: Pack blocks: (use the "Individual blocks" form shown above for each block)


I imagine these blocks could become part of a more comprehensive programming tools library. I have several candidates (to be continued).

Oh good grief there are two of you. :~P

Comments in code are all a bad idea, be they balloon ones or inline ones. (Short version: Programs should be documented at a high level of abstraction, not line by line.)

Minor suggestion about the presentation: Because the blocks are gray, and so are the rings, even though not quite the same gray, it took me forever to work out how the last two blocks differ. I'm sure when you're actually using the blocks, so they don't have rings around them, it's much easier. But, for the purpose of this program documentation (in a useful form, not as code comments!! Good job.) I would add text to the descriptions along the lines of "(Note: This is a COMMAND block.)"

I added a little note to the top of each block's description, just reading "Shape: (SHAPE)."

I don't like block comments in snap, specifically because they also get ran, rather then snap just skipping them, like the built in snap balloon comments.

I’m not going to repeat my arguments in favor of in-source comment blocks. If you don’t like them, nsimply don’t use them.

That's fine for you. But I'm a teacher; I want to teach people why inline comments are a bad idea. (All the more so because they'll hear the opposite from everyone else.)

also. snap has a comment feature

I know, we inherited it from Scratch (remember, the original BYOB was a direct mod of their code) and even I am not so extreme as to want to remove an existing feature just because I don't like it.

And of course I do like putting comments on the hat block in the Block Editor to make help screens for custom blocks. I'm pretty sure that was my idea, although I don't entirely trust my memory these days.

i dont like using comments in code. when i code i usually write all logic down on a paper when im bored and then just mess around comments are too hard to see

I told my students that any time I'm tempted to put a comment inside a script, I take that to mean that I'm being too clever and that I should rewrite the code to be self-documenting instead of commenting it. This is true; once a month or so I'd find myself putting a comment inside a procedure, and I'd catch myself doing it, and rewrite the procedure top to bottom. If I can't read my own code without a comment, something is wrong.

My programming teacher actually tells us to comment our code. I tend to write code without comments, and then go back to add comments, just to get full credit. I prefer to write self-documenting code, as it's less green text to ignore.

Yeah, they all do. Except me.

This fight has a long history. Back a million years ago, when (to a first approximation) all the computers were made by IBM, they had a rule for their programmers that before you could write a program, you had to draw a flowchart, which was a very detailed drawing of the line-by-line design of the code.

Somewhere I still have my IBM Flowcharting Template.

(If it's not clear, the green thing on top is a piece of plastic with holes cut out; the thing on the bottom is a paper sleeve to hold it. Mine is actually a little different from this one, because when I learned to flowchart, calling a subroutine was a rectangle with its top left corner cut off, kind of like the punch card symbol but a bigger cutoff. The sleeve in the picture says that calling a subroutine is a rectangle with a narrower rectangle inside it.

Anyway, the point is, IBM's programmers universally worked by writing the code, then making the flowchart and giving it to their manager, then waiting a few days, then handing in the code. Eventually someone wrote a program called AUTOFLOW that would take your (assembly language) program and draw a flowchart automatically. It was very popular! So, you should write a program like that to put comments in your code for your teacher to read. :~)

By the way, there was a convention for putting comments in a flowchart. A comment was a rectangle off to the side, connected by a dashed line to the actual program box it describes -- just like our balloon comments!

The fact that flowcharting could be automated (remember, this was half a century before ChatGPT) shows how little information is actually conveyed in flowcharts. The same is definitely true about line-by-line comments.
untitled script pic (2)

By the way, in fairness, I have to say that exactly once in my life I wrote a flowchart voluntarily, for a piece of code I didn't (still don't) understand even though I wrote it: the core evaluator in the Berkeley Logo interpreter.

I emphasize that I drew this entirely for myself! Since then other people have taken over Berkeley Logo maintenance, and maybe it's useful for them. But even more useful for them is that I wrote something else I learned about at IBM: a Program Logic Manual. This is the kind of high-level program documentation that I propose instead of inline comments.
plm (68.7 KB)

They still tell us to do that. I've seen some videos about programming, and they say to write a flowchart before jumping into the code. My teacher has also said to write pseudocode before writing the code, which is kind of the same sense. I feel like that rule isn't practiced very much these days, but some people still tell others to do it.

My problem with pseudocode anf flow charts before writing thr code is, I may realize what I wrote before was wrong, or there's a better way of doing it. Although whenever I get a prompt for a program, I start thinking about how to program it, kind of like a flow chart in my mind. I personally think that there are some benefits to writing pseudocode or flow charts before writing a program, but sometimes it's better to just jump right into the code.

I agree. I usually write the code, then think about what it would do AFTER, then change the code accordingly. I also change the code if there are any bugs.

Ooh, this pushes my buttons even more than inline comments. I am firmly convinced that nobody in the world, including your teacher and all the other people who genuinely believe they write pseudocode before they write the program, actually do. I'm confident about this because you can't write the pseudocode until you know what you can write in the pseudocode that's actually translatable into runnable code, and you know that because you've written the code in your head and then translated it into pseudocode.

SICP gives the example of this square root "program" in pseudocode (except they do it in pseudo-Scheme):

define sqrt(x) {
  return y such that y*y = x

Why isn't that perfectly good pseudocode? Only because you tried writing it in some actual programming language, and it had no such "such that" feature. Well, how about this:

define sqrt(x) {
  let S be the set of all computable numbers
  return y𝜀S such that y*y = x

That's in my programming language, right?

No, you have to write an actual program before you can write a handwavy version that isn't too handwavy.

Down with pseudocode!

Oh yeah, my teacher's definition of pseudocode, is just explain the steps that the program takes, not something that looks like code, but isn't.

Even so, how do you know what a "step" is? Answer: You write the actual code in your head, then (or maybe in parallel) you translate each line into fuzzyscript.

This block may be useful for reporting something with comments:

This wouldn't report the first input, but the second input.
You may find this very useful.

Block name: Comment with Report
Block help: Reports the second input, optionally allowing you to add a comment in the first input.
Function and/or Purpose: Useful for projects that are using lots of reporters.

I added it to the project, and credited you for the idea.