search

HAL-RO-Developer / iot_plat_doc

2 stars 0 forks source link

命名規約の決定 #50

Open show-t opened 7 years ago

show-t commented 7 years ago

背景

プログラミングにおけるファイル名、クラス名、メンバ名、メソッド名の規約を設けることでチーム内で困惑が起こらないようにする。

目的

対応内容

命名規約をまとめて文書化する。

期日

７/5

hiyanaka commented 7 years ago

Arduinoの命名規約を作成

hiyanaka commented 7 years ago

Arduinoコーディング規約

目的

Arduino IDEでコードを書く上で変数や定数の名前をつけることで、初めてソースを見た人でも何に使われている変数なのか、どのような処理を行っている関数や引数かを明確にする。

全般

エンコーディング（文字コード）

UTF-8

インデント

コメント

開始時のコード表現

/*
    スケッチタイトル

    制御内容を簡潔に表現する.個々のピンに接続されたコンポーネントを参照する.

    The circuit:
    * 各inputに接続されているコンポーネントのリスト
    * 各outputに接続されているコンポーネントのリスト

    Created 年月日
    By 著者名
    Modified 年月日
    By 著者名

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

*/

ファイル名

変数

クラス

メンバー変数

"_"+ローワーキャメルケース または ローワーキャメルケースのいずれかを使う

構造体名

定数定義名

列挙型（enum）名

グローバル変数名

アッパーキャメルケースを使う

ローカル変数名

全て小文字のスネークケース または ローワーキャメルケースのいずれかを使う

メソッド

hiyanaka commented 7 years ago

関数

メンバ変数

ローワーキャメルケース

構造体名

アッパーキャメルケース

ローカル変数

ローワーキャメルケース

hiyanaka commented 7 years ago

ArduinoIDEコーディング規約

はじめに

目的

本規約は，ArduinoIDEに記述されたプログラムの品質向上を目的に，守るべき最低限のルールを規定し、 コードの可読性・保守性・メンテナンス性の向上を目的とする。

定義、頭文語、略語

無し

全般規約

エンコーディング（文字コード）に関する規約

コードは、UTF-8で記述する。

インデントに関する規約

インデントはスペースキーで行い、幅は４のみ許可する。

コンパイラに関する規約

コンパイラレベルは最高レベルに設定し、警告は全て取り除くこと。 ArduinoIDEでは、ファイル→環境設定→より詳細な情報を表示する項目のコンパイルにチェックを入れ、 コンパイラの警告を全てに設定する。

ファイル内部構成

ソースファイル・ヘッダファイルの内部構成は以下のルールとする。

  1. ファイルヘッダ 本ファイルの説明が記載されている。
  2. 関数ヘッダ 関数の概要・引数・戻り値の型と意味が記載されている。
  3. 関数処理（実体） 実際のプログラムが記述されている。 setupとloopは、以下のようにプログラムの最初に記載する。
  4. ファイルフッタ 全プログラムの最後に著作権が記載されている。
ファイルヘッダ

関数ヘッダ
void setup() {
  処理
}

関数ヘッダ
void loop() {
  処理
}

関数ヘッダ
関数処理() {
  処理
}

ファイルフッタ

ヘッダに関する規約

ファイルヘッダに関する規約

ファイルヘッダには、ファイル名、プロジェクト名、機能概要、更新履歴、更新日付、作成者氏名、includeファイル情報、typedef宣言(ヘッダのみ)、定数定義(同ファイルで用いるもののみ記述する。 複数ファイルで使用する定数の場合はヘッダへ記述)、グローバル変数宣言。 ファイルヘッダは、ヘッダファイル、ソースファイルの共に適応する事。

/*
  ファイル名

  制御内容を簡潔に表現する。
  個々のピンに接続されたコンポーネントを参照する。

  The circuit:
   * 各inputに接続されているコンポーネントのリスト
   * 各outputに接続されているコンポーネントのリスト

  Created 年月日
  By 著者名
  Modified 年月日
  Place 変更箇所
  By 著者名
*/
/*
  includeファイル
*/

/*
  typedef宣言
*/

/*
  定数定義
*/

/*
  グローバル変数
*/

使用例

/*
  LEDFlashing.ino

  LED点滅回路
  16番ピンに接続されたLEDを点滅させる。

  The circuit:
   * input:none
   * output:16

  Created 2017/07/01
  By Hirotaka Nagaoka
  Modified 2017/07/05
  Place 点滅周期変更
  By Hirotaka Nagaoka
*/
/*
  includeファイル
*/
#include <arduino.h>
#include "ESP8266WiFi.h"
/*
  typedef宣言
*/
typedef enum statusLED{
    OFF = 0,
    ON
} STATUS_LED;
/*
  定数定義
*/
#define PIN_LED 16
/*
  グローバル変数
*/
static unsigned int flagState = 1;

ファイルフッタに関する規約

ファイルフッタには権利ロゴを記述する。

/*
  Copyright HAL College of Technology & Design
*/

関数ヘッダに関する規約

各種関数開始の前に、以下の規約に従って関数ヘッダを記述する。関数ヘッダには、以下の項目を 記述する。関数名、機能名、機能概要、引数の型、引数名、I/O情報、引数の解説、戻り値の型、 戻り値の値、作成日、作成者。

/*
  関数名

  機能名

  機能概要

  引数:

  戻り値:

  Created 年月日
  By 著者名  
*/

使用例

/*
  LEDFlashing

  LED点滅

  LEDを一定周期で点滅させる。

  引数:
  STATUS_LED led   LED点滅関数実行前のLEDの状態

  戻り値:
  STATUS_LED       LED点滅関数実行後のLEDの状態

  Created 2017/07/01
  By Hirotaka Nagaoka
*/

ファイル名に関する規約

単語は英語を主体とする。ローマ字は認めない。また、英字の略語は許可する。 ファイル名は「アッパーキャメルケース」で統一すること。 例)IotPlatFormSetup.ino ヘッダーファイルは、機能名を採用する。 例)ESP8266Setup.h

関数名に関する記述

単語は英語を主体とする。ローマ字は認めない。また、英字の略語は許可する。 関数名は「ローワーキャメルケース」で統一すること。 例)getPortState

関数名 スコープ位置に関する規約

関数のスコープ開始位置は、関数名の１行下に記述すること。 後述する制御文のスコープ位置とは扱いが異なる為注意すること。

関数記述に関する規約

関数の引数が存在しない場合、必ずvoidを付与すること。

スペースに関する規約

各項目に特別な表記が無い限り、以下の規約に従う。

  1. 演算子とオペランドの間 a += 1; ※アロー、ドット、インクリメント、デクリメント演算子は例外とする。

  2. 制御文・関数等と丸括弧の間 if( a )

  3. 制御文・関数等が終わる等の丸括弧と中括弧の間 switch( c ) {

  4. カンマの後ろや処理を区切る部分等 func( a, b ); for( a = 0; a < 20; a ++ ) {

コメントに関する規約

コメントは、/* */もしくは、//で記述する。 ただし、どちらかで統一すること。共存は認めない。 本仕様書では、統一性を出すために/* */で記述している。

変数による規約

変数に関する定義・宣言に関する規約を以下に示す。

変数名に関する規約

単語は英語を主体とする。ローマ字は認めない。また、英字の略語は許可する。 変数名は「アッパーキャメルケース」で統一すること。 例)buttonState

グローバル変数名に関する規約

単語は英語を主体とする。ローマ字は認めない。また、英字の略語は許可する。 グローバル変数名は「g_+ローワーキャメルケース」で統一すること。 例)int g_State = STATE_NONE

構造体定義に関する規約

単語は英語を主体とする。ローマ字は認めない。また、英字の略語は許可する。 構造体型名は「全て大文字&スネークケース」で統一すること。 構造体メンバ名は全て意味のある英単語及び略語、また、全て小文字で表記を行う。

定数・マクロに関する規約

単語は英語を主体とする。ローマ字は認めない。また、英字の略語は許可する。 定数名は「全て大文字&スネークケース」で統一すること。 例)#define PIN_MODE 1

show-t commented 7 years ago

また、/* */と//は統一すればどちらでもOKとしてるけど、ヘッダフォーマットの規約的に、/* */に固定されないか。 どちらでも可とするならば、//版のヘッダフォーマットも必要なのでは？ もしくは、条件付きで//を許可するとか。( 処理コメントに限るなど）

まず、ざっくり読んで気になったのは以上の点です。ご確認よろしくお願いします。 修正および修正報告後、クラス関連の規約を追加してください。 あと、Issueページが長くなるので、workフォルダにアップロード、コメントにパスを記載で対応してください。

hiyanaka commented 7 years ago

https://github.com/HAL-RO-Developer/iot_plat_doc/blob/master/work/nagaoka/ArduinoCodingStandards/ArduinoCodingStandards.md