blockly -- Custom Blocks: Style Guide

Custom Blocks: Style Guide

多年来，区块和区块游戏团队已经吸取了许多教训，适用于开发新区块。以下是我们所犯的错误，或其他人常犯的错误的集合。

这些是我们在使用Blockly的视觉风格时学到的一般经验，可能并不适用于所有的用例或设计。其他解决方案存在。这也不是用户可能遇到的问题以及如何避免这些问题的详尽列表。每个案例都有点不同，都有自己的取舍。

1. Conditionals vs. Loops

对于新用户来说，最困难的块是条件和循环。许多基于块的环境将这两个块分组到同一“控件”类别中，两个块具有相同的形状和颜色。当新用户混淆这两个块时，这通常会导致挫败感。Blockly建议将条件和循环移动到单独的“逻辑”和“循环”类别中，每个类别都有不同的颜色。这清楚地表明，这些是不同的想法，表现不同，尽管有相似的形状。

建议：将条件和循环分开。

2. One-based Lists

新手程序员第一次遇到基于零的列表时反应很差。因此，BBLLY遵循Lua和LAMBDA MOO的领先地位，通过列表和字符串索引之一。

对于Blockly的更高级使用，支持基于零的列表，以便更容易地转换到文本。对于年轻或更多的新手观众，仍然推荐基于一个索引。

建议：一是第一个号码。

3. User inputs

从用户获取参数有三种方法。下拉列表是最具限制性的，对于简单的教程和练习非常有用。输入字段允许更多的自由，有利于更多的创造性活动。值块输入（通常带有阴影块）提供了计算值（例如随机生成器）的机会，而不仅仅是静态值。

建议：选择适合用户的输入方法。

4. Live block images

块的文档应该包括它所引用的块的图像。截屏很容易。但是如果有50个这样的图像，并且应用程序被翻译成50种语言，那么突然一个应用程序就维护了2500个静态图像。然后颜色方案改变了，2500张图片需要更新——再一次。

为了从这个维护噩梦中解脱出来，Blockly游戏用Blockly以只读模式运行的实例替换了所有屏幕截图。结果看起来与图片相同，但保证是最新的。只读模式使国际化成为可能。

建议：如果支持多种语言，请使用只读模式。

5. Your other Left

来自美国儿童的反馈（虽然有趣的不是来自其他国家）揭示了左右之间的混乱。通过添加箭头解决了这个问题。如果方向是相对的（例如，相对于化身），箭头的样式很重要。当化身面向相反的方向时，A→直箭头或A↱转向箭头会造成混淆。最有用的是⟳圆形箭头，即使在旋转角度小于箭头指示的情况下也是如此。

建议：尽可能用Unicode图标补充文本。

6. High-level Blocks

在可能的情况下，应该采取更高级别的方法，即使它降低了执行性能或灵活性。请考虑以下应用程序脚本表达式：

SpreadsheetApp.getActiveSheet().getDataRange().getValues()

在保留所有潜在功能的1:1映射下，将使用四个块构建上述表达式。但是Blockly的目标是更高的级别，并且将提供一个封装整个表达式的块。目标是对95%的病例进行优化，即使这使剩下的5%更加困难。Blockly并不是要取代基于文本的语言，而是要帮助用户克服最初的学习曲线，从而使用基于文本的语言。

建议：不要盲目地将整个API转换为块。

7. Optional Return Values

在基于文本的编程中，许多函数执行一个操作，然后返回一个值。此返回值可以使用，也可以不使用。例如堆栈的pop（）函数。可以调用Pop来获取和删除最后一个元素，或者调用它来删除最后一个元素，并忽略返回值。

var last = stack.pop();  // Get and remove last element.
stack.pop();  // Just remove last element.

基于块的语言通常不擅长忽略返回值。值块必须插入接受该值的内容。有几种策略可以解决这个问题。

a） 避开这个问题。大多数基于块的语言设计语言是为了避免这些情况。例如，Scratch没有任何既有副作用又有返回值的块。

b） 提供两个街区。如果工具箱中的空间不是问题，那么一个简单的解决方案是为每种类型的块提供两个，一个带返回值，一个不带返回值。缺点是，这可能会导致一个包含许多几乎相同块的混乱工具箱。

c） 变异一个街区。使用下拉列表、复选框或其他控件，允许用户选择是否有返回值。然后，块根据其选项更改形状。Blockly的列表访问块就是一个例子。

d） 吃掉价值。App Inventor的第一个版本创建了一个特殊的管道块，该块接受任何连接的值。用户不理解这个概念，App Inventor的第二个版本删除了管道块，而是建议用户简单地将值赋给一个一次性变量。

建议：每种策略都有利弊，选择适合你的用户的策略

8. Growing blocks

某些块可能需要可变数量的输入。例如，对任意一组数字求和的加法块，或具有任意一组else if子句的if/elseif/else块，或具有任意数量初始化元素的列表构造函数。有几种策略，各有利弊。

a） 最简单的方法是让用户用更小的块组成块。一个例子是通过嵌套两个两个数字加法块来添加三个数字。另一个例子是只提供if/else块，并让用户嵌套它们以创建elseif条件。

这种方法的优点是它最初的简单性（对用户和开发人员都是如此）。缺点是，在存在大量嵌套的情况下，代码变得非常麻烦，用户很难阅读和维护。

b） 另一种方法是动态扩展块，以便在末尾始终有一个自由输入。同样，如果最后有两个自由输入，则块删除最后一个输入。这是App Inventor的第一个版本使用的方法。

App Inventor的用户不喜欢自动增长的块，原因有两个。首先，总是有一个免费的输入，程序永远不会“完成”。其次，在堆栈中间插入一个元素是令人沮丧的，因为它涉及到断开编辑下面的所有元素并重新连接它们。也就是说，如果顺序不重要，并且用户可以在他们的程序中使用漏洞，这是一个非常方便的选择。

c） 为了解决孔问题，一些开发人员在块中添加了+/-按钮，这些块可以手动添加或删除输入。Open Roberta使用两个这样的按钮从底部添加或删除输入。其他开发人员在每行添加两个按钮，以便可以从堆栈中间插入和删除。另一些则在每一行加上两个向上/向下按钮，以便可以适应堆栈的重新排序。

这种策略是一系列选项，从每个块只有两个按钮，到每行四个按钮。一端是用户无法执行所需操作的危险，另一端是用户界面充满了按钮，看起来就像星际飞船企业号的桥梁。

d）最灵活的方法是向块中添加一个突变泡。这表示为打开该块的配置对话框的单个按钮。元素可以随意添加、删除或重新排列。

这种方法的缺点是，对于新手用户来说，它的变异并不直观。引入变异需要某种形式的指导。针对年幼儿童的基于块的应用程序不应使用突变子。虽然一旦学会了，它们对电力用户来说是无价的。

 

建议：每种策略都有利弊，选择适合你的用户的策略。

9. Clean Code Generation

高级Blockly用户应该能够查看生成的代码（JavaScript、Python、PHP、Lua、Dart等），并立即识别他们编写的程序。这意味着需要付出额外的努力来保持机器生成的代码可读。多余的括号、数值变量、压碎的空白和冗长的代码模板都会妨碍生成优雅的代码。生成的代码应该包含注释，并且应该符合Google的风格指南。

建议：为您生成的代码感到骄傲。显示给用户。

10. Language Dependence

对干净代码的渴望的一个副作用是Blockly的行为在很大程度上是根据交叉编译语言的行为定义的。最常见的输出语言是JavaScript，但是如果Blockly要交叉编译到另一种语言，就不应该做出不合理的尝试来保持两种语言之间的精确行为。例如，在JavaScript中，空字符串为false，而在Lua中为true。为Blockly的代码定义一个单独的行为模式来执行，而不管目标语言是什么，这将导致无法维护的代码看起来像是来自GWT编译器的。

建议：Blockly不是一种语言，允许现有语言影响行为。