コンテンツ記述用Arduinoスタイルガイド

初心者から上級者までが読むことができる、わかりやすいArduinoの例の記述方法を学びます。

LAST REVISION: 2023/01/20 03:14

これは、初心者から上級者までが読むことができる、わかりやすいArduinoの例を記述するためのガイドです。この方法で書く必要はありませんが、全てのレベルのユーザにわかりやすいコードにする場合、役に立ちます。これは厳密なルールではなく、ガイドラインの集合です。これらのガイドラインのいくつかには矛盾もあります。いつガイドラインに従うべきなのかは、自分で判断してください。わからない場合は、あなたの書いたものから学ぶつもりの人に、何が最もわかりやすいのかを尋ねてください。ライブラリ作成用Arduinoスタイルガイドも参照してください。。

Arduinoドキュメントのウェブサイトにコンテンツを寄稿したいときは、Arduinoドキュメントリポジトリ内の、contribution-templatesフォルダに説明があります。

チュートリアルを書く

このほとんどは、長年にわたり、多くの人から借用したもので、コードを書くときに従うガイドラインのリストが以下です。

  • 能動態で書いてください。
  • あなたの文書に従う人が同じ部屋にいるかのように、明確に、会話風に書いてください。
  • 指示するときは、二人称で書き、自分が実施するということを、読者が理解するようにしてください。
  • 重文ではなく、簡単な平叙文や指示を書いてください。一度に一つの指示を理解する方が読者には簡単です。
  • 以下のように、明確に指示してください。
    • 次に、センサーの値を読みとり…
    • thisPinという変数を宣言し…
  • 情報のない言葉は使わないでください。「ピンを設定したいでしょう」ではなく、「ピンを設定してください」と書いてください。
  • 回路図だけでなく、写真や絵と回路図を使ってください。電子工作を趣味とする多くの人は回路図を読めません。
  • 仮説を確認してください。チュートリアルで使った全ての概念を読者が理解していますか?そうでなければ、それらを説明するか、説明している他のチュートリアルへのリンクを張ってください。
  • 物事を概念的に説明し、読者が何をしようとしているのかの全体像を理解できるようにしてください。そして、それらをどのように使うのかを一つずつ説明してください。
  • 初めて専門用語を使うときは、定義してください。全ての新しい用語を定義したか、誰かに確認してもらってください。一つか二つは、見逃している可能性があります。
  • 利用する用語には、一貫性を持たせてください。要素や概念を新しい名前で参照するときは、他の名前と明確な関係を持たせてください。2つの単語に互換性があることを伝えずに、2つの用語を相互に使わないでください。
  • 頭字語や略語は、最初に綴らずに利用しないでください。
  • 例は一つのことをするようにしてください。概念を組み合わせるチュートリアルでない限り、概念や機能を組み合わせないでください。

コード例を書く

効率ではなく、読みやすさが最重要です。

Arduinoのもっとも重要なユーザは、初心者でコードにこだわりはなく、プロジェクトを完遂させることに興味があります。

あなたよりコードに詳しくない人には寛大になってください。技術的な概念を理解するべきだとは思わないでください。彼らは理解しませんが、そうだからと言って愚かでもありません。説明が不要なコードとしてください、あるいは、コメントを使って説明してください。レジスタや割り込み、ポインタなどの複雑な概念が必要な時は、説明するか説明をとばしてください。

技術的に簡単か技術的に効率的かを選ばばければならないときは、前者を選んでください。

概念は、有用な時にだけ導入してください。各例では、導入する新しい概念は。最小限にしてください。例えば、まず最初は、int型以外の変数やピン番号を定義する定数を使わない、単純な関数の説明をしてください。一方、中級の例では、有用になる周辺の概念を導入したくなるでしょう。ピン番号を定義するconst intの利用や、0から255以外の値を使わないときは、intではなくbyteを選択するなどは、有用ですが、入門段階では主要なものではありません。このため、これらは控えめに使い、レッスン計画で、それらの概念が新しい概念となるときに説明してください。

setup()とloop()は、プログラムの最初に配置してください。他の全ての関数はこれら2つから呼ばれるので、初心者がプログラムの概要を理解するのを助けます。

コードにコメントを入れる

  • 全ての変数や定数の宣言に、その変数が何をするのかの説明をコメントしてください。
  • 全てのコードブロックにコメントしてください。できれば、ブロックの前でコメントしてください。読者は何が来るのかがわかります。
  • 全てのforループにコメントしてください。

詳細なif文を使ってください。初心者がわかりやすいように、全てブロック形式を使ってください。すなわち、以下は避け、

1

if (distance > 10) moveCloser();

代わりに、以下を使ってください。

1
2
3

if (distance > 10) {
   moveCloser();
}

ポインタは避けてください。

#defineは避けてください。

変数

  • 一文字の変数名は避けてください。変数を説明するようにしてください。
  • valやpinのような変数名を避けてください。buttonStateやswitchPinのように、より説明的にしてください。

変更されないピン名や他の量を定義するときは、const intを使ってください。#defineよりも面倒がなく、変数と定数の違いを教えることができます。

可能な時は、wiring/Processingタイプの変数名を使ってください。例えば、boolean、char、byte、int、unsigned int、long、unsigned long、float、double、string、array、voidです。uint_8などは避けてください。前者はドキュメントで説明されていてより簡明な名前です。

ユーザを混乱させる番号付けは避けてください。例えば、

1
2

pin1 = 2
pin2 = 3

ピン番号を付け替える必要があるときは、配列をつかってください。例えば、

1

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

これにより、配列要素を使って新しいピン番号を参照することができます。例えば、

1

digitalWrite(myPins[1], HIGH);  // turns on pin 7

好きな順序でピンをオン・オフすることができます。例えば、

1
2
3
4
5
6

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

コード例

タイトルブロックのいい例です。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

/*
    Sketch title

    Describe what it does in layman's terms.  Refer to the components
    attached to the various pins.

    The circuit:
    * list the components attached to each input
    * list the components attached to each output

    Created day month year
    By author's name
    Modified day month year
    By author's name

    http://url/of/online/tutorial.cc

*/

回路

デジタル入力スイッチでは、プルアップ抵抗ではなく、プルダウン抵抗を使うのがデフォルトです。これにより、非エンジニアに対しても、スイッチの相互作用の論理が、わかりやすくなります。

回路は簡潔にしてください。例えば、バイパスコンデンサは便利ですが、ほとんどの単純な入力は、バイパスコンデンサがなくても動作します。追加の構成要素がある場合は、後で説明してください。

オリジナルのページ

https://docs.arduino.cc/learn/contributions/arduino-writing-style-guide

最終更新日

January 29, 2023

inserted by FC2 system