もともと、読まれることの方が多い
もともと「ドキュメントやコードは書くよりも読まれることの方が多い」という考えなので、書くときにできるだけがんばって、読む人ができるだけ読みやすいものにしたいと意識している。
というのも、意識していないとついつい、書いて終わりになってしまう。そのときは頭の中に色々入ってるから読みやすさとか考えなくても理解できているし、書くのは書くので大変だから「よし書き終わった！ちゃんと動いた！」で「できた！」って言いたいし。なんなら次のタスクにはやくとりかからなきゃって焦ってたりもする。
そして、あとからそのドキュメントやコードを見た人が「これどういうことだっけ・・・」って悩みながら読み解いたりする。それは半年後の自分かもしれない。
だから、書き終わった後に「これは読む人にとって読みやすいか？」を考えて見直すようにしている。コードでうまく説明できているか、背景をコメントで残しておくほうがいいか、関数の名前が内容を正しく表現できているか、間違ってはいないけど余計なコメントをつけてしまっていないか、などなど。ドキュメントを書くときも同じ。これはどういう立場の人が読むのか。その人にとって必要十分なものになっているか。
最近は、書く労力が下がった
最近は、生成AIによって、ドキュメントやコードを書く労力がすごく下がった。ちょっとAIと会話したら、いい感じのドキュメントが生成される。そして、その内容はだいたい正しいことを言っている。だから、そのドキュメントをそのまま渡してしまっても問題はない。
だけど、生成AIが生成したものって、読む方の負担がわりと大きい。いろいろ書いてあるけど、結局どこが要点だっけ・・・というのを読み手が考えながら読まないといけないし、必要なのに書かれていないこと、もあったりするから「・・・あれ？これについて書いてなくない・・・？」ってなったりしながら読む。疲れる。
だから、自分がドキュメントを書くときは、AIに生成してもらった時点では3割ぐらいの完成度のつもりで捉えている。ぱっと見た感じだと8割ぐらいの完成度に見えるんだけど。情報が多すぎたり、本当に必要な部分が分かりにくかったり、日本語の言い回しに違和感があったりで、そういうのを修正していく。10分で生成したものを数時間かけて修正したりする。
自分が「大変だなぁ」って思いながらやってるその修正作業は、そのまま渡してしまうと読み手に強いてしまう苦労なので、もともとと同じ「読まれることの方が多い」という考えで修正するようにしている。
生成AIによって書く労力は下がったけど、手元の情報が増えたぶん読みやすいドキュメントを書くのは今までより難しくなった感覚がある。ただ、ちゃんと読みやすさを考えて手直しをすれば、生成AIを使っていなかったときよりもずっといいドキュメントになるなぁとは思っている。
コードは・・・
コードも似たような感覚ではあるけど、こっちはもうちょっと「読みにくいものが生成されたらプロンプトの方を修正したほうがいい」という感覚ではあるかな。
ただ、今どきは読み手もAI
読みやすさを考えて作業したりしてはいるのだけど、今どきみんなドキュメントも生成AIに読んでもらってから要点を教えてもらったりしてると思うので、まぁ、どっちでもいいかという気持ちも半分ある。実際、生成AIで書いたままだなぁって思うようなドキュメントを見ても、あまり気にせずにAIと一緒に読んだりしている。
なんとなく
ところで、プルリクエストのレビューコメントに対しては、いったん生成AIに読み込ませて対応を考えて修正をしたりする。そのときに、レビュー用エージェントやAIを使って書いただろうなってコメントには手元のAIから返事をさせている。
でも、人が手で書いてくれたなってコメントには手で返事を書くようにしている。ただ、僕が手で書いたコメントに対して、他の人が生成AIで返事をしてきても、あまり気にしてない。
自分はなんとなくそうしているってだけ。
まぁこういうことも、今後はなくなっていくんだろうなぁって思いながら、手でコメントを書いたり、ドキュメントを手直ししていたりする。
