コメントは技術的負債になりやすい
プログラミング内のコメント
PHPDocやJSDocみたいな、動的型付け言語でのアノテーションのDocsも好かない
上と同じ理由
アノテーションとしてのコメントで挙動に差異を生む場合ますます紛らわしい
これは「コメント」だと見なさないほうがいいな
「今は使っていないコードを一時的にコメントアウト」も好かない
邪魔である
git使ってるんだからそれで振り返ればいいじゃん
「一時的」は大抵の場合ずっと残り続ける
代替案
型こそが仕様である
型を見れば意図がわかるようにしたい
型システムの柔軟性が必要
TSの型はやや柔軟だがsyntaxが見づらすぎるmrsekut.icon
型と実装がズレることはない
ずれればコンパイルエラーになる
エラーが出たということは実装か型のどちらかが明確に間違っている
テストコードを書く
コメント無しで挙動がわかりにくいならテストコードを書けばいい
引数と戻り値でなんとなくの挙動が予想できる
しかも実装に追従する
関数を分割する
複雑すぎるなら小さく関数を切ればいい
再利用のための関数分割ではないことに注意
適切な関数名や引数名で説明するという方法もある
簡単に見えて割と難易度が高いと思うmrsekut.icon
具体的には想像できないが、そこが問題なのでそこを解決すればいい
めちゃくちゃちゃんとコードレビューをする
コメントを残して、コメントが生きているかどうかをレビュアーが全部目で確認する
mrsekut.iconはやりたくない
実装からズレる恐れがないコメントならいい
そのファイルの責務が明確に決まっていればそれについてのコメントはズレない
その関数の責務が明確に決まっていればそれについてのコメントはズレない
↑いずれもP→QのPを守るのが難しいmrsekut.icon
特に複数人開発の場合
責務を述べるコメントは良さそうmrsekut.icon
責務こそがそれの存在意義なので。
責務がズレるならそれは存在する意味がない
消して新しく作られることになる
ズレたときはその対象を放棄するタイミングになる
もしくは再検討
最初のあなたの抽象化の仕方が間違ってましたよ、の気付きにつながる