どこかに書いておきたいドキュメントまとめ

[Hiroshiba]

内容

まとまってないけど、どこかにまとめないともったいなさそうだったので。

どこかに書いておきたいドキュメントを、とりあえず一旦ここに集約させる目的です。

[Hiroshiba]

シンボル（Hoge.fugaみたいな）の使い方に関しての案

初出のシンボルをシンボルのまま書かない。わからないから。
わからないシンボルを説明するときは、人がわかるところから書く。前提の説明とか、より広い概念の紹介とか。
説明を書くとき、１回はシンボルに接地させる。コードと結びつかなくなるから。

以下は仮説段階

仮説、シンボルを使うのは１回だけ。ドキュメント全体で数十回出てくるならシンボルそのまま使っても良い。英語より日本語のほうが認知負荷が低いから。
仮説、`Class.propertyOrFunction`のシンボルを説明するとき、`Class.`は要らない。無くても伝わるような説明にしたほうがわかりやすいから。どうしても説明できない場合は`Class.`を書いても良い。

[Hiroshiba]

案：
リポジトリに何か新しいツールを追加したとき、それについて必ず何かしらドキュメントを書く。
それは何なのか、目的、方針が１行ずつだけでも良い。

追加した目的をメンテナーが見失わないように＋新規コミッターが意図と違う貢献をしてしまわないように＋AIがレビューしやすいように。

[Hiroshiba]

案：括弧書きは極力辞める。

補足説明なら、後ろに書く。

ボリュームライン（折れ線と塗りつぶし）を描画するクラス。
↓
ボリュームラインを描画するクラス。折れ線と塗りつぶしを描く。

[Hiroshiba]

バグをなるべく減らすためのあれこれ：

• エラーの握りつぶしを避ける。早期発見が期待できる。
• 連動する複数の値はなるべく直和型を使う。おかしなステートを避けられる。