kdoc - 命名/ネーミング/コーディングルール

  • 作成日：2015-01-20 10:30:24
  • 修正日：2017-10-20 15:06:17

設計およびコーディング時のルール

↑ページトップへ

おれ流。

  • インデントはスペース×2 （Mojolicious, Railsはスペース×2）
  • 空行にはインデントなし （Mojolicious, Railsはなし）
  • 1行は最大80文字
  • コメント識別子（# とか // とか）の後ろ、スペース×1
  • ファイル末尾の改行あり

データベース

↑ページトップへ

  • テーブル名は単数形で。
カラム名 説明とか
id プライマリキー
lock_version 編集バージョンキー。AさんとBさんが同時更新をかけないように。rails由来
position ソートキー。rails由来
created_at 作成日時
created_by 作成者。user_idが入る
updated_at 更新日時
updated_by 更新者。user_idが入る
カラム名 説明とか
user_id userテーブルへリレーション
user_count userテーブルの関連レコード数のキャッシュ
name 名前
name_en 名前アルファベット表記
title 　
key アルファベットのみ。インデックス張りがちな値
value 　
account 　
xxxxx_at 日時が入る
xxxxx_by user_idが入る
xxxxx_date 日付が入る。YYYY-MM-DD
xxxxx_time 時間が入る。hh:mm:ss
memo メモ
comment コメント
remark 備考
is_deleted 削除フラグ（deletedだけだと日付が入ったりしそうなので）

postfix

_id 整数のみ。他テーブルへの参照キー
_key アルファベット含む
_at 日時
_by たぶんユーザID
_name 名
_title タイトル、ラベル
_text 改行を含むテキスト
_value わかんない。キーに対して？

NULL/デフォルト値

  • NOT NULL制約をなるべく付ける。
  • デフォルト値NULLをなるべく避ける。
  • NULLとゼロと空が重複して存在して欲しくない。

以下、可能であれば。

  • 文字列なら「（空）」。
    • NULLと空を区別したい時のみNULL可とする。
    • 空がまずいなら「未定義」。
  • 数値ならゼロ。
  • 日付なら「0001-01-01」、第二候補「9999-12-31」。
  • フラグならゼロ。
  • 右/左/未入力なら、1/2/0とか。

メモ

  • MySQL の InnoDB は外部キー制約をサポート

メソッド名

↑ページトップへ

# 他動詞
find data

# 副詞は動詞の後ろ？（前の場合もある）
deleteDirectoryRecursively()
findStrictly()

# 過去分詞は形容詞になる
sent message 送信済みのメッセージ
deleted rows : 削除された行（削除行）
duplicated rows : 重複した行
nested list : ネストしたリスト
distributed processing : 分散された処理（分散処理）
supported OS : サポートされたOS
defined function : 定義された関数（定義関数）
selected row : 選択された行

# 現在分詞も形容詞に
existing file 存在しているファイル

# 接頭語、接尾語
pre＋動詞 prepend、preprocess
re＋動詞 redo、redeploy
名詞＋ize serialize、Romanize、camelize、normalize、parameterize
動詞＋able serializable、sendable、comparable

Google JavaScript Style Guide

↑ページトップへ

→Google JavaScript Style Guide 和訳 — Google JavaScript Style Guide 和訳

node.js

↑ページトップへ

→Felix's Node.js Style Guide(和訳)

  • インデント: スペース×2、文末セミコロンあり、1行80文字、シングルクォート（JSONではダブル）、変数「adminUser」（×「admin_user」）、クラス名「BankAccount」、定数「SECOND」
// パーレンの前後のスペース、ブレスを開いて閉じる揃え方
if (true) {
  console.log('!');
}

// 1行で1宣言
var a = 'aaa';
var b = [12, 23];

// NG
var a = 'aaa',
     b = [12, 23];

// いったん分かりやすい名前付ける
var isAuthorized = (user.isAdmin() || user.isModerator());
if (isAuthorized) {
  console.log('winning');
}

// NG
if (user.isAdmin() || user.isModerator()) {
  console.log('losing');
}

HTML5

↑ページトップへ

jQuery

↑ページトップへ

→JavaScript Style Guide | Contribute to jQuery

Cocoa(Apple)で許可される略語

↑ページトップへ

→Acceptable Abbreviations and Acronyms

  • alloc(Allocate), alt(Alternate), app(Application), calc(Calculate), dealloc(Deallocate), func(Function), horiz(Horizontal), info(Information), init(Initialize), int(Integer), max(Maximum), min(Minimum), msg(Message), nib(Interface Builder archive), pboard(Pasteboard), rect(Rectangle), Rep(Representation), temp(Temporary), vert(Vertical)
  • ASCII, PDF, XML, HTML, URL, RTF, HTTP, TIFF, JPG, PNG, GIF, LZW, ROM, RGB, CMYK, MIDI, FTP

ネーミング全般

↑ページトップへ

語

↑ページトップへ

aとthe、anyとsome

a
それと別物を置き換えても文章が成り立つ場合。
どれでもいいのが a
the
それでないと文章が成り立たない場合。
それじゃないと駄目なのが the

some に対応するのが the 、any に対応するのが a です。

注意事項その1:固有名詞にはtheをつけない

大文字、すなわち固有名詞になっている場合にはtheはつけない。これは the internet と Internet の場合も同様です。これは、プログラマー的な理解にも合致します。theはいわば「固有化オペレーター」なので、すでに固有化されているものに二重にかける必要はない、というわけ。

ただしこれにもこれまた例外がありまして、「固有フレーズ」の場合はtheを取り除けない。the United States のように。

注意事項その2:作品紹介では a を使う

洋画の冒頭を見て下さい。"a Walt Disney film"だとか、"a Kurosawa movie"とかという表記になっているはずです。極めつけに、"A Fish Called Wanda"なんて映画まであります。 a と the の違いから考えれば、これは the が正しそうに思えますが、なぜかこういう場合は a なのです。

実はこれ、例外というよりは一般原則の拡張でもあります。この場合、"Kurasawa movie"を一つの単語だと考えるのです。そうすれば"'Spirited Away' is a Miyazaki film. The movie won the Academy Award in 2001."という文章でもとまどいません。

スペルミス

元々はindicesのみが正解だったのが、indexesも後に認められるようになった。

matrixも最近ではmatricesと書く人よりmatrixesと書く人の方が多いような気もする。

それと同じ道を歩みつつあるのが、、referer。正解は"referrer"なのだけど、