ソースコードのコメント文をどう書くか
ChatGPT.icon要約
友人とのソースコードの話で、「コメントを書かなさすぎ」と指摘された経験があるという相談がありました
関数名を適切にすることが重要であるという意見が出されましたが、関数名だけではコードの意図を正確に伝えることが難しい場合があります。そのため、どの程度のコメントを書けば見やすくなるかについて悩んでいるようです。
込み入った処理の場合は処理内容を書くことが提案されました。
ただし、大きすぎる場合は関数に分割することが望ましいとされています
コメントを書くかどうかはコードの読み書きに自信がある人には必要ないとされていますが、一般的にはコメントを書くことが推奨されます。
Mijinko_SD.icon
この前友人とソースコードの話になったけれど、「お前コメント文書かなさすぎ」みたいなのを言われた（実際は違う言われ方したけれど） JSDocとかはある程度書いているので、命令文の間に書く説明文をどれだけ書くべきか、という話になる https://gyazo.com/75ee7f8f5c81320540fca85c43c64407
↑こういうの
普段はこれを書くぐらいだったら別の関数に分けている
上記の画像のコードは、2行しかなかった上に他で使い回すことも無かった（というか使いませるように書き直すとわりと面倒）ので、例外的にそのまま書いた
関数名はIDEでまとめて修正できるけどコメントはまとめて修正できないから基本的には関数名を適切にすることの方が重要nishio.icon
重要といえるのだろうか？楽とはいえそうだけどもyosider.icon
確かに少し飛躍があった(こういうツッコミ助かる)nishio.icon
1: 関数名の方が「実態を表すように修正するのが楽」
2: だから関数名の方がコメントよりも「実態を表すようにつけられているだろう」とコードを読む人が思うだろう
3: だからその期待を裏切らないように関数名を適切にすることが重要
というステップをすっ飛ばして3の話を書いてた
自分だったら、コメントがあればコメントが一番わかりやすく説明してくれているだろうと期待しそうyosider.icon
わかりやすい≠実態を反映している、ではある
関数名やコメントが修正されない問題基素.icon
どの程度書けば見やすくなるのかがわからない
書きすぎ（というよりはコメントに頼り切るの）が良くないことは知っている
関数名は、コメント文を読むまでどういう動きをするのか全くわからないような名前にはするなとか
逆に（JSDocとかを除いた単純なコメント文を）どういった場面なら書いたほうが良いのかというのがわからない コードの字面じゃわからないようなテクニックとかtakker.icon
例：[...new Set([...list.map((item) => {/* ... */})])]
Setを噛ませているのは重複除去をするためだけど、JS慣れてない人がこれを見ても重複除去だとすぐ気づくのは難しい
takker.iconはもう慣れてしまったので、いちいちコメント書かない
同じく綾坂こと.icon
Setとスプレッド(もしくはArray.from())で重複除去するのは頻出だと思っている
こういうのに// 重複を除くなどと書くとわかりやすいかも
+1yosider.icon
ロジックが汎用的なら関数に切り出してremoveDoublesとか名づけると良いのでは？inajob.icon
removeDuplicates?yosider.icon
それが一番ですtakker.icon
あとは込み入った処理の冒頭に、処理内容を書くくらい？
あんまりに大きいやつは函数に切り出すのがbetter
コメント、ChatGPTとかがいい感じに書いてくれないだろうかyosider.icon
ついでに改善点のアドバイスも
改善点はアドバイスしてくれたtakker.icon
ケースバイケースsta.icon
コードがっつり読み書きする人だけなら、なるべくコメント書かずに名前を工夫する
そうじゃない人がいる or 多いなら（後の修正コストや冗長性は出るだろうが）コメントも書く