Arduino编程风格（译）

原文：Arduino style guide
地址：https://www.arduino.cc/en/Reference/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 = 2
pin2 = 3
etc.

• 如果你需要重新编号引脚，考虑使用数组，如下所示：

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许可证授权，您可以自由分享，修改，或者引用，引用时希望您尊重个人努力成果，注明来源。个人水平有限，不足之处还望多多指正