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