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


インデント幅は空白2つ

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

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

空白の数は2つが理想ですが、4つに慣れているユーザを考慮し、少し広めの3つ指定という選択もあります(3文字幅インデント …)。

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

省略出来るものは出来るだけ書かない

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

これで十分

printf("%f", 3.1);

ここまでしなくて良い

#include <stdio.h>

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

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

#include <stdio.h>
int main() { printf("%f", 3.1); }

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

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

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

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

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

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

std::cout << "Shop " << 99 << std::endl;
// 出力結果: "Shop 99"

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

変換結果
atof(“99″)99
atof(“1e2″)100
atof(“0xF”)15

途中式の扱い

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

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

マイナス数字の扱い

数字部分を揃えます。

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

コードを揃える

関連する処理や共通した処理であることを読み手に示す意図があります。また右辺と左辺の対応を明確にする意図もあります。可読性や判読性が向上し読み手の負担も軽減する利点が生まれます。規則性の見出しやすいコードを書くよう意識しましょう。

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; // `/`
}

セミコロンは省略しない

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

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

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

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

広告

関連するオススメの記事