原文：Arduino style guide
地址：https://www.arduino.cc/en/Reference/StyleGuide
译者注：本文将告诉你如何写一个Arduino示例，文中介绍了Arduino规范化编程的一些准则，这些准则在其他语言编程中同样适用，因此具有一定的参考价值！

这是一个用于编写规范的Arduino示例的指南，适合初学者和同样也适合高级用户使用。当然您大可不必按照这种方式编程，但是如果您想要您的代码可以让不同水平的都可以清晰的读懂，那么它可以帮到您。这不是一套强硬的准则，仅仅只是一些参考。有些参考甚至可能彼此冲突。利用您的判断力在何时这些指导原则最通顺上，如果您不确定，咨询那些将要通过您写的例子学习的人，这会让您有更好的理解。另外您有可能对Arduino API风格指南感兴趣。

写一个教程

（大部分内容是从多年来各家的编辑那里引用来的）

请用主动语态写
语言写得清楚直白，就像遵循你的指令的人和你在一个房间一样。
在给一些指令时，最好用第二人称，以便读者明白她将是执行者。
请使用短小,简洁的陈述句或命令而不是复合句。这可以让读者更容易一次消化一个指令。
请给出明确的指示就像：
“下一步，你将要读取传感器”
“创建一个名为thisPin的变量”
避免没有意义的短语。不要告诉读者“您要设置引脚”这样的指示，只需要告诉她“设置引脚”
请使用图片和原理图，而不是仅仅只有原理图。许多电子爱好者不读原理图。
检查你的假设。读者是否理解您在教程中使用的所有概念？如果没有，解释或链接到另一个教程。
从概念上解释事物，这样读者对他将要做的就有一个大的了解。然后安排如何一步一步的执行指令。
每当您初次使用一个技术术语时，请先定义它。请人帮忙您检查您是否定义了所有的新术语，您有可能会漏掉其中一两个。
请与您使用过的术语保持一致。如果您通过新名称引用元件或概念，请将其与其他名称的关系明确显示。除非您明确告诉读者两个术语是等价的，否则不要使用两个可以互相交换的术语。
在没有拼写出它们的全称前不要使用缩写词或缩写
让您的例子更加简洁有针对性。除非是关于组合概念的教程，否则不要组合概念或功能。

#写示例代码

稳定比效率更重要。
Arduino的主要用户都是一些不关注代码的初学者，他们关心的重点是项目的完成。
别人比你了解代码少是很正常的事。不要认为他们需要理解一些学术概念。他们不需要，他们不理解代码不是因为他们愚蠢。你的代码应该可以自我解释，或者使用注释来做同样的事情。如果需要一个复杂的概念，如寄存器、中断或指针，要么解释它，要么跳过它。
在面临技术上简单和高效选择时，请选择前者。
除非介绍的概念很有用，否则尽量少介绍并且在每个例子中减少新概念的数量。例如，在刚开始，您可以解释没有int以外的变量类型的简单函数，也可以用常数来定义引脚号。另一方面，在一个中间的例子中，您可能希望引入周边概念，因为它们变得有用。像使用const ints来定义引脚号的概念，当你不需要超过0 - 255时，在int中选择字节等等是有用的，但这不是入门的核心。所以请谨慎使用它们，并在新教程中解释它们。

请将


# 注释你的代码

* 注释所有的变量和常量声明，并且声明变量的作用。
* 注释所有的代码块。如果可能的话，在代码块前注释，这样读者就能了解代码块的作用。
* 注释所有的循环。
* 使用详细的if语句。即为了可以将代码更加直观的呈现给读者，请使用程序块格式进行所有操作。避免使用下面这种格式：

if (somethingsIsTrue) doSomething

1	用下面这种格式代替：

if (somethingsIsTrue==True){
doSomething;
}

1 2	* 避免使用指针 * 避免使用```#define

变量

避免使用单字母变量名。使它们具有描述性。

避免使用像

1
2
3

* 如果要定义引脚名称和其他不会改变的数值，请使用const ints。他们与#defines相比不是那么凌乱，但仍然给你一种讲解变量和常数之间的区别的方法。
* 使用接线/处理类型的变量类型，例如 boolean，char，byte，int，unsigned int，long，unsigned long，float，double，string，array，void，如果可能的话，尽量不用uint8_t等。前者在文档中有说明，更简洁的名称。
* 避免让用户混淆的编号方案，像：

pin1 = 2
pin2 = 3
etc.

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

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

1	* 这允许您使用数组元素来引用新的引脚号，如下所示：

digitalWrite(myPins[1], HIGH); //打开引脚7

1	* 它还允许您按照所需的顺序打开或关闭所有引脚，如下所示：

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

1
2
3


# 刚开始就解释代码
这是一个很好的标题块：

/*
程序标题
从一个外行人的视角来解释程序的功能。请参阅各种引脚附件。
电路：

列出每个输入组件
列出每个输出组件
创建年月日
创建者名字
修改年月日
修改者名字
http://url/of/online/tutorial.cc
*/
```
电路
- 对于数字输入开关，默认是在开关上使用下拉电阻，而不是上拉。这样，开关的交互逻辑对非工程师是有意义的。
- 保持您的电路简单。例如，旁路电容器是方便的，但是大多数简单的输入可以在没有它们的情况下正常工作。如果一个组件是偶然的，请稍后解释。
- 更正，建议和新的文件应该发布到论坛。

Arduino参考文本以Creative Commons Attribution-ShareAlike 3.0许可证授权。指南中的代码示例将公布到公共区域。

个人学习翻译作品，感谢好友@Morning在翻译过程中提供的指导
继承Arduino开源精神，本文同样以Creative Commons Attribution-ShareAlike 3.0许可证授权，您可以自由分享，修改，或者引用，引用时希望您尊重个人努力成果，注明来源。个人水平有限，不足之处还望多多指正