In earnest: an FAQ post is ex cathedra. It can only be written by a Snap! staff member (I guess); and it has no “Reply” button, so ordinary users can not talk back. By implication (in accordance with the well-know adagium noblesse oblige) FAQ posts should adhere to high standards. Though I, for one, truly enjoy an occasional rant (both bh and jens are masters of the genre), FAQ is not an appropriate category (IMAO) for personal opinions.
I do think a good discussion of code documentation in Snap! would be useful. This may result in a guideline (for primitives, libraries; perhaps even for code one asks for help with) - one that’s widely accepted ideally, or at least awarded the status of an official policy; to be published either as FAQ or Tutorial.
I guess that topic could be moved to Announcements. That's my best guess, where people could reply to open topics created only by staff. Currently, it's in technical, on which only staff could reply to open topics there.
Whn moved, you should be able to reply to there. Just wait for the staff to move to there.
That’s hilarious - I wonder if any other programming language’s “official” forum has such section. Can hardly wait for an anthology of the most outrageous among jens’ rants on various subjects such as ignorance, cheekiness, and JavaScript.
Good!
Now here’s some thoughts of mine (non-exhaustive) on Snap! code documentation.
In-code documentation is a part of a larger body of documentation of a programming language (or environment). Some other parts may be tutorials, the reference manual, release notes, and design documents.
This body of documentation should aim at (no less than) three categories of people - deliberately leaving out datascrapers & AI - 1. novice users; 2. experienced users; 3. system programmers.
Novice (& casual) users will want to have a general idea of what a block does, and (insofar as these are not trivial) its inputs and outputs. In Snap! this is implemented as the online-Help, embodied by a comment attached to a block definition’s hat block. Other than that novice & casual users may use tutorials. They’re not likely to look into a custom block’s definition, nor consult the reference manual (or even know of its existence).
Experienced users (& autists) will want to know exactly what a block does, what limitations apply on inputs, any special cases, probable causes of errors, etc. They are not unlikely to read the reference manual now and then, and may want to look into a custom block’s definition.
I propose the reference manual will contain these data for all primitive blocks - this may be a separate section; and libraries will be self-documenting in this respect. The latter may take various forms, such as a comment text (or block) immediately below the hat, a (annotated) demonstration script within the block definition window, or even a separate library documentation block.
Programmers (& testers) will want to document the architecture of a block, a group of blocks / library, a/o data structure. This is probably done best in separate design documents, so not in-code. When writing a library I, for one, often use demonstration scripts within the block definition window for testing changes.
bh Convinced me that comments at random positions within a script are to be avoided whenever possible. If you need those, either your script has become too large a/o complicated, or variable names should be made self-explanatory.
Anyone asking for help with a piece of code I recommend to not only organize their code (while removing clutter), but also to use annotated demonstration scripts showing what works, and what doesn’t.
So I have decided against writing a response, because I'm long past telling people what I want without being able to prove it.
However, I will say I agree with most of what QW23 says.
The only thing I would suggest, is instead of having a pdf manual seperate, have it inline in snap, and have it use my favourite snap feature, the drag and drop, to take code from the manual, place it in snap and watch it work while you read the manual.
I rarely comment any of my code, and I never comment my code in a block based programming language like snap. In the context of snap, I just feel like there is no reason to, since most code in snap is already human readable and understandable (that's what's awesome about block based languages). When it comes to text based languages, I feel like if you're having to write a comment explaining a piece of code, then you need to change your variable names, or make it easier to read.
One of the biggest reasons why I feel like commenting your code is redundant, is because code is already supposed to be human readable instructions for the computer. Why do I need to explain what the instructions are doing? You should just be able to figure it out.
I'm also not the only one who agrees with this, because I have watched a couple youtube videos talking about comments in code.
The only times I use comments, is when it's something that is actually hard to understand, and there's not really any way to change it to make it more readable. I also add comments to functions, explaining what the function does, and all it's arguments. Basically just documentation. Doing that is actually very helpful for other people, because I find it very helpful when I'm writing code in python.
I agree with this if it's a complicated function of 3 or more inputs that does something non-obvious. But it drives me crazy when high school CS teachers make kids attach such comments even to things like
char toLowercase(char ch)
which is what most functions in most programs should be like imho.
I feel like my programming teacher last year was not very strict on things. Heck, there was a piece of code I had to write on a test, and accidentally used ^ instead of ** in python (for context, ** is the power operator, rather than ^ in python), but he still gave me full credit because he understood what I meant to do (and it's an understandable mistake). My point is, near the end of the year, we had some projects with a rubric, which said that we had to comment our code. I feel like my teacher would still give full points if I didn't comment much of my code.
I did also take a web development class, and I'm pretty sure that teacher didn't talk much about commenting your code. The most he said was sectioning a css file (we didn't do much in javascript).
In current Snap! the following functions though non-trivial are not supported by any online help - they happen (?) to be mostly from the Control category:
Besides some complicated topics, such as different behavior of reporter-if vs. “normal” if when dealing with non-atomic inputs is not documented in the reference manual, nor dictionary features in list handling, nor limitations of .
Yeah, all the lack of documentation is my fault. For several years now I've been not getting my job done, including the help system and the manual. Y'all are more than welcome to help with help screens! Here are blank helpscreen backgrounds for narrow and wide blocks:
These are at .../help/BLANK.png and BLANKWIDE.png in the repo.
Really they should just give up on me and either make Jadga be in charge of documentation or make SAP hire another person to do it. But I selfishly don't want that. :~/
P.S. But that has nothing to do with comments in code; we just repurposed comments on hat blocks to mean help texts for custom blocks.
.
