ブログ用コーディング規約｜プログラミング系記事をスマートに書く

目次

インデント幅は空白２つ

画面の小さなモバイル端末を意識し、インデント幅は可能な限り小さくします。タブは使わず空白を用いるようにします。

ブラウザによってはタブは空白８つ分の幅で表示されてしまうことがあります。

空白の数は２つが理想ですが、４つに慣れているユーザを考慮し、少し広めの３つ指定という選択もあります。

参考: ３スペース インデントのススメ｜空白３つコーディングへの考察

上級者向けの記事や階層が深めのコードでは空白２つを用い、初心者向けの記事では３〜４の空白を用いるのも良いでしょう。

省略できるものはできるだけ書かない

上級者・中級者向けの記事ではヘッダーのインクルードやライブラリのインポート、main関数等は必要に応じて書くようにし、可能な限り省略するようにします。

これで十分

printf("%f", 3.1);

ここまでしなくて良い

#include <stdio.h>

int main() {
   printf("%f", 3.1);
}

いいセンスだ、今回は見逃してやる

#include <stdio.h>

int main() {
   printf("%f", 3.1);
}

本当に伝えたい重要な情報のみを載せるようにします。コード量は少ないほうが読む側の負担も減ります。また重要な情報を相手に印象づける効果も生まれます。余計なネストも不要になり、コードの行数も削減できます。

読者ターゲットに合わせてコードを書くよう意識しましょう。

ヘッダーインクルードを簡潔に表現する

特定のライブラリの関数や定数の説明を行う際には、ヘッダーのインクルードをきちんと行います。

#include <assert.h>

void sample_assert() {
   assert(1 == 2);
}

サンプルコードが冗長的になる場合には、コメントを用いて補足的な記述を行います。

// #include <assert.h>
assert(1 == 2);

必要に応じ、インクルード元で利用している関数や定数をコメント形式で記述します。対象の機能がどのヘッダで定義されているかが明確となります。

#include <float.h> // DBL_EPSILON
#include <math.h>  // fabs

#define DBL_EQ(x, y) (fabs(x - y) < DBL_EPSILON)

出力結果はコード内に書く

プログラムの出力結果はコード内にコメントとして埋め込みます。

printf("Shop %d", 99); // "Shop 99"

初心者向けの記事の場合は、よりわかりやすくするために詳細なコメントを付け加えるのも良いでしょう。

std::cout << "Shop " << 99 << std::endl;
// 表示結果： "Shop 99"

場合によっては表形式にしたほうが読みやすくなります。

変換結果
atof("99")99
atof("1e2")100
atof("0xF")15

色々と工夫すると良いでしょう。

// Good
printf("%d", 99); // 99
// Good
printf("%d", 99); // => 99
// Pretty Good
printf("%d", 99); // "99"
int a = 1;
++a; // a == 2
++a; // a: 3
++a; // {a: 2}
++a; // {a == 2}

途中式の扱い

必要であれば、計算結果や途中式の結果もコード内に埋め込みます。

int i = 100;
i += 1; // 101
++i;    // 102
i++;    // 102
printf("%d", i); // "103"

マイナス数字の扱い

数字部分を揃えます。

int max = INT_MAX; //  2147483647
int min = INT_MIN; // -2147483648

初学者への対応

コード内に処理の結果をコメントとして埋め込むという発想は、初学者を混乱させる恐れがあります。

atoi("9");   //  9
printf("9"); // "9"

補足を加えることでこれを解消することもできます。

atoi("9");   // 変換結果: 9
printf("9"); // 出力結果: 9

式形式のコメントを記述することも有効です。

int i = atoi("9"); // i == 9

モバイル環境での表示を考慮し、ヨーダ記法による記述を行うことも有効です。

int i = atoi("9"); // 9 == i

モバイル環境ではワードラップ無効時にコードが途中で途切れてしまうことがありますが、ヨーダ記法を用いれば重要な結果（9）の部分が途切れずに表示される確率が高まります。

参考: ヨーダ記法とは｜定数を左辺に記述するメリットと流行らない理由

コードを揃える

規則性の見出しやすいコードを書くためのテクニックです。

int left  = 1;
int right = 2;

このように似たような処理が複数あるような場合は、それぞれの代入位置やキーワードの位置を揃えるようにします。これによってそれぞれの処理が共通した処理や関連した処理／宣言であるということを読み手に示すことができます。

またこのようなコード整列は、右辺と左辺の対応を明確にする意図もあります。可読性や判読性が向上し読み手の負担も軽減する利点が生まれます。

switch (align) {
  case Left:  return "L";
  case RIght: return "R";
}

printf("Shop %d" , 99);  // "Shop 99"
printf("DAISO %d", 100); // "DAISO 100"

enum Operation {
  Addition       =  2; // `+`
  Subtraction    =  4; // `-`
  Multiplication =  8; // `*`
  Division       = 16; // `/`
}
case a: return 1;
case b: return -1;
↓
case a: return  1;
case b: return -1;
↓
case a: return +1;
case b: return -1;
assert( "a".equals("a") );
assert( !"a".equals("b") );
↓
assert(  "a".equals("a") );
assert( !"a".equals("b") );
参考: コード整列のススメ｜読みやすいコードを意識するプログラミング作法

セミコロンは省略しない

// Good
console.log("Pen-Pineapple-Apple-Penpineapple-Pen");
// NG
console.log("Pen-Pineapple-Apple-Penpineapple-Pen")

画面の小さなモバイル端末ではテキスト折り返しによってコードが改行されて表示される事があります。特に複数コードが改行無しで書かれているような場合には複数行の判別が難しくなります。

セミコロンを付けることで、文の終わりを明確にする意図があります。

Swift言語やJavaScript言語ではセミコロンの省略ができますが、文字数の多い行では可能な限りセミコロンを付けるようにすると良いでしょう。セミコロンを省略する場合は改行を適宜用いるようにします。
なおこれらの問題はCSSでテキスト折り返しを無効にすることで対処も可能です。

コメントについて

コメント内で変数名を利用する場合にはシンボル名をバッククオート（`）で囲います。

int i = 99; // 変数`i`は整数型
広告