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不是一種語言，允許現有語言影響行為。