Test-Scratch-Wiki:Block Plugin Style Guide

Translate: - English 

Shortcut:
S:SB2STYLE

In order to keep the Scratch Wiki looking neat, please follow the following style guide when writing <scratchblocks> on the wiki.

Feel free to fix any articles that do not conform to this guide.

This guide is intended for wiki editors, and includes guidelines on style as well as a little extra syntax. It thus serves a different purpose to Block Plugin/Syntax, which is intended for forum users and wiki editors alike.

Style Guide

Whitespace

• Always put a line break before and after the opening and closing <scratchblocks> tags.

No:

I like this script: <scratchblocks>when flag clicked
say [Hello!]</scratchblocks> Pretty, isn't it?

Yes:

I like this script:

<scratchblocks>
when gf clicked
say [Hello!]
</scratchblocks>

• However, if you're writing a script with a single block, only use one line:

Yes:

<scratchblocks>when gf clicked</scratchblocks>

• Use indentation. Always indent by 4 spaces. (This is for consistency as much as for any other reason.)

No:

repeat (10)
if <touching [mouse-pointer v]?>
move (10) steps
end
stamp
end

Yes:

repeat (10)
    if <touching [mouse-pointer v]?>
        move (10) steps
    end
    stamp
end

• Always put whitespace around inserts and embedded blocks. This is easier to read.

No	Yes
if<mouse down?> then	if <mouse down?> then
<(variable)=[3]>	<(variable) = [3]>
(join (((3)*(3))+((3)/((3)-(3))))[j])	(join (((3) * (3)) + ((3) / ((3) - (3)))) [j])
set size to (100)%	set size to (100) % Note: This last example is currently broken due to a mysterious wiki-only bug.

• Always put spaces around the comment symbol "//".

No:

stamp//Draws a picture!

Yes:

stamp // Draws a picture!

Be Explicit

The block plugin will close brackets and c-blocks for you, in case you forget. Do not rely on this; always include properly formatted scripts in wiki articles. If Javascript is disabled then the source code will be displayed directly to the user, so the scratchblocks code in articles needs to be readable.

• Always include "end" after a C block.

No:

repeat (10)
    move (10) steps
    stamp

Yes:

repeat (10)
    move (10) steps
    stamp
end

• Always close brackets.

No:

if <<(x position) < [3]> and <(var) = [4

Yes:

if <<(x position) < [3]> and <(var) = [4]>>

Misc

Warning: The wiki does not support double-colon syntax yet. Go bug scmb1 to update the plugin! :) --blob8108 12:04 20 September 2014

• Replace "(user id)" with "(user id :: sensing)". The user id block is deprecated, and may be removed from scratchblocks in the future.

No:

set [foo v] to (user id)

Yes:

set [foo v] to (user id :: sensing)

Scratch 2.0 Blocks

Make sure you use the 2.0 versions of blocks (unless it's an article specifically about Scratch 1.4). This includes:

Scratch 1.4	Scratch 2.0 replacement
switch to costume [costume1 v]	switch costume to [costume1 v]
switch to background [background1 v]	switch backdrop to [background1 v]
next background	next backdrop
(background #)	(backdrop #)
if <>	if <> then
forever if <>	forever if <>
stop script	stop [this script v]
stop all	stop [all v]
when Sprite1 clicked	when this sprite clicked
<loud?>	<(loudness) > [30]>

Wiki-only features

There are some extra "hidden" features intended for use on the wiki only.

Ellipsis

• The grey . . . ellipsis block represents a gap in a script. Use it!

Do not write the word "script", "scripts", any other obsolete block, or a comment saying "script goes here".

No:

forever
    if <>
        script
    end
end

No:

forever
    if <>
        // script goes here
    end
end

Yes:

forever
    if <>
        . . .
    end
end

• Always put spaces between the dots: . . .. This makes the block easier to read.

Inline Scratchblocks

You can place scratchblocks inside a sentence using the <sb> tag, like this:

I'm rather fond of the <sb>stamp</sb> block in Scratch 2.0.

Producing:

I'm rather fond of the stamp block in Scratch 2.0.

Notes:

• You can only use a single block in the inline tag, not a whole script.

• Use inline scratchblocks to represent variable names, e.g. (score):

No:

Use the "score" variable to keep track of...

Yes:

Use the <sb>(score)</sb> variable to keep track of...

• For block links, use inline scratchblocks instead of images:

Yes:

[[Stamp (block)|<sb>stamp</sb>]]

stamp

• Do not use inline scratchblocks in headings.

No:

== The (username) block ==

Yes:

== The username block ==

Colouring blocks

Warning: The wiki does not support double-colon syntax yet. Go bug scmb1 to update the plugin! :) --blob8108 12:04 20 September 2014

You can set the colour of blocks using secret hacks. This allows you to colour blocks that would normally appear obsolete, for example the "create clone" block from the Scratch 2.0 prototype.

create clone

By using a special hack, you can get the correct colour:

create clone :: control

Notes:

• For colouring blocks, do not use the deprecated comment syntax, which may be removed in the future. Use the more flexible double-colon syntax instead, which also supports reporters:

No:

create clone // category=control

Yes:

create clone :: control

say (ultrasonic sensor :: extension)

External Links

• Complete List of Blocks
• Test page