Arduino编程风格(译)

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

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

写一个教程

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

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

  • 在没有拼写出它们的全称前不要使用缩写词或缩写

  • 让您的例子更加简洁有针对性。除非是关于组合概念的教程,否则不要组合概念或功能。

#写示例代码

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

    # 注释你的代码

    * 注释所有的变量和常量声明,并且声明变量的作用。
    * 注释所有的代码块。如果可能的话,在代码块前注释,这样读者就能了解代码块的作用。
    * 注释所有的循环。
    * 使用详细的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许可证授权,您可以自由分享,修改,或者引用,引用时希望您尊重个人努力成果,注明来源。个人水平有限,不足之处还望多多指正

坚持原创技术分享,您的支持将鼓励我继续创作!