原文：Arduino style guide

地址：Arduino - StyleGuide

譯者註：本文將告訴你如何寫一個Arduino示例，文中介紹了Arduino規範化編程的一些準則，這些準則在其他語言編程中同樣適用，因此具有一定的參考價值！

這是一個用於編寫規範的Arduino示例的指南，適合初學者和同樣也適合高級用戶使用。當然您大可不必按照這種方式編程，但是如果您想要您的代碼可以讓不同水平的都可以清晰的讀懂，那麼它可以幫到您。這不是一套強硬的準則，僅僅只是一些參考。有些參考甚至可能彼此衝突。利用您的判斷力在何時這些指導原則最通順上，如果您不確定，諮詢那些將要通過您寫的例子學習的人，這會讓您有更好的理解。另外您有可能對Arduino API風格指南感興趣。

寫一個教程

（大部分內容是從多年來各家的編輯那裡引用來的）

• 請用主動語態寫
• 語言寫得清楚直白，就像遵循你的指令的人和你在一個房間一樣。
• 在給一些指令時，最好用第二人稱，以便讀者明白她將是執行者。
• 請使用短小,簡潔的陳述句或命令而不是複合句。這可以讓讀者更容易一次消化一個指令。
• 請給出明確的指示就像：
  「下一步，你將要讀取感測器」

  「創建一個名為thisPin的變數」

  避免沒有意義的短語。不要告訴讀者「您要設置引腳」這樣的指示，只需要告訴她「設置引腳」
• 請使用圖片和原理圖，而不是僅僅只有原理圖。 許多電子愛好者不讀原理圖。
• 檢查你的假設。讀者是否理解您在教程中使用的所有概念？ 如果沒有，解釋或鏈接到另一個教程。
• 從概念上解釋事物，這樣讀者對他將要做的就有一個大的了解。 然後安排如何一步一步的執行指令。
• 每當您初次使用一個技術術語時，請先定義它。請人幫忙您檢查您是否定義了所有的新術語，您有可能會漏掉其中一兩個。

• 請與您使用過的術語保持一致。如果您通過新名稱引用元件或概念，請將其與其他名稱的關係明確顯示。除非您明確告訴讀者兩個術語是等價的，否則不要使用兩個可以互相交換的術語。

• 在沒有拼寫出它們的全稱前不要使用縮寫詞或縮寫

• 讓您的例子更加簡潔有針對性。除非是關於組合概念的教程，否則不要組合概念或功能。

寫示例代碼

• 穩定比效率更重要。
• Arduino的主要用戶都是一些不關注代碼的初學者，他們關心的重點是項目的完成。
• 別人比你了解代碼少是很正常的事。不要認為他們需要理解一些學術概念。他們不需要，他們不理解代碼不是因為他們愚蠢。你的代碼應該可以自我解釋，或者使用注釋來做同樣的事情。如果需要一個複雜的概念，如寄存器、中斷或指針，要麼解釋它，要麼跳過它。
• 在面臨技術上簡單和高效選擇時，請選擇前者。
• 除非介紹的概念很有用，否則盡量少介紹並且在每個例子中減少新概念的數量。例如，在剛開始，您可以解釋沒有int以外的變數類型的簡單函數，也可以用常數來定義引腳號。另一方面，在一個中間的例子中，您可能希望引入周邊概念，因為它們變得有用。 像使用const ints來定義引腳號的概念，當你不需要超過0 - 255時，在int中選擇位元組等等是有用的，但這不是入門的核心。 所以請謹慎使用它們，並在新教程中解釋它們。
• 請將setup()（聲明函數）和loop()（循環函數）放在程序開頭。它們幫助初學者了解程序的概況，因為所有其他功能都是從這兩個方法調用的。

注釋你的代碼

• 注釋所有的變數和常量聲明，並且聲明變數的作用。
• 注釋所有的代碼塊。如果可能的話，在代碼塊前注釋，這樣讀者就能了解代碼塊的作用。
• 注釋所有的循環。
• 使用詳細的if語句。即為了可以將代碼更加直觀的呈現給讀者，請使用程序塊格式進行所有操作。避免使用下面這種格式：

  if (somethingsIsTrue) doSomething

  用下面這種格式代替：

  if (somethingsIsTrue==True){ doSomething; }

• 避免使用指針
• 避免使用#define

變數

• 避免使用單字母變數名。使它們具有描述性。
• 避免使用像val和pin這樣的變數名。讓它們更加具有描述性，像buttonState或者switchPin。
• 如果要定義引腳名稱和其他不會改變的數值，請使用const ints。他們與#defines相比不是那麼凌亂，但仍然給你一種講解變數和常數之間的區別的方法。
• 使用接線/處理類型的變數類型，例如 boolean，char，byte，int，unsigned int，long，unsigned long，float，double，string，array，void，如果可能的話，盡量不用uint8_t等。前者在文檔中有說明，更簡潔的名稱。
• 避免讓用戶混淆的編號方案，像：

  pin1 = 2pin2 = 3etc.

• 如果你需要重新編號引腳，考慮使用數組，如下所示：

  int myPins[] = { 2, 7, 6, 5, 4, 3 };

• 這允許您使用數組元素來引用新的引腳號，如下所示：

  digitalWrite(myPins[1], HIGH); //打開引腳7

• 它還允許您按照所需的順序打開或關閉所有引腳，如下所示：

  for (int thisPin = 0; thisPin < 6; thisPin++) { digitalWrite(myPins[thisPin], HIGH); delay(500); digitalWrite(myPins[thisPin], LOW); delay(500);}

剛開始就解釋代碼

這是一個很好的標題塊：

/* 程序標題 從一個外行人的視角來解釋程序的功能。請參閱各種引腳附件。 電路： * 列出每個輸入組件 * 列出每個輸出組件 創建年月日 創建者名字 修改年月日 修改者名字 http://url/of/online/tutorial.cc*/

電路

• 對於數字輸入開關，默認是在開關上使用下拉電阻，而不是上拉。 這樣，開關的交互邏輯對非工程師是有意義的。
• 保持您的電路簡單。例如，旁路電容器是方便的，但是大多數簡單的輸入可以在沒有它們的情況下正常工作。 如果一個組件是偶然的，請稍後解釋。
• 更正，建議和新的文件應該發布到論壇。

Arduino參考文本以Creative Commons Attribution-ShareAlike 3.0許可證授權。指南中的代碼示例將公布到公共區域。

個人學習翻譯作品，感謝好友@Morning在翻譯過程中提供的指導

繼承Arduino開源精神，本文同樣以Creative Commons Attribution-ShareAlike 3.0許可證授權，您可以自由分享，修改，或者引用，引用時希望您尊重個人努力成果，註明來源。個人水平有限，不足之處還望多多指正

推薦閱讀：