◆ JSDoc などの /** */ が嫌い
  ◆ ブロックコメントなのに各行に * を入れるムダな装飾
  ◆ ネストできないブロックコメントなので 広範囲のコメント化と競合
◆ C# の /// が好きだけど XML なのはイマイチ
◆ 調べてみると /// で XML じゃない doc comment の言語は色々あった

コメントの記法の中で特別な書き方をする doc comment というのがあります
ほとんどは言語側の機能ではなくサードパーティ製のライブラリが処理するものですが 標準機能みたいな感じで使われてることも多いです

JavaScript だと JSDoc というものでこういう書き方です

/**
* ここに説明
*/
function foo() {}

説明のところには引数や返り値などの情報も書けます
個人的にはほとんど書かないのですが 丁寧に書いておきたいところだと書いておこうかなと思うこともあります
ですが この記法が個人的にはすごく嫌いです

嫌なところ

まずブロックコメントになってます
ブロックコメントはネストできないので これがあると複数の関数にまたがる範囲をまとめてコメントアウトしたいときに困ります
エディタによっては範囲指定してコメントアウトを選べば全部の行に // のような行コメントを入れてくれる機能があったりしますが 個人的にはこれよりも開始点と終了点にブロックコメントの開始と終了記号を入れるほうが好きです

また 「ここに説明」 の行のように ブロックコメントにしてるのに行コメントのようなすべての行の最初に 「*」 が必要です
こういう無駄な装飾はやめてほしいです
全部の行の始まりに記号を入れるくらいなら最初からブロックコメントではなく行コメントを使えばよいです
それに エディタの補助があってもコピペなどが入ってくると この 「*」 がすごく邪魔になります

通常コメントと区別するための何かが必要なのはわかりますが それならこういう感じの最初と最後の行だけにして欲しかったです

/********
ここに説明
********/

ベストは ///

私が思うベストなものは 「///」 です
行コメントですし 「//」 に一本 「/」 が増えただけでシンプルです

C# では 「///」 を使うので JavaScript とは違って結構積極的に書いていました
「///」 と入力するだけで VisualStudio がほとんどを補完してくれる便利さです

ただ 唯一の欠点が XML なところです
C# では 「///」 を使いますが その中のコメントエリアでは XML で各情報を記述します
マイクロソフトは XML 好きなのでなんかわかりますが 人が読み書きする上で XML はあまり良いものには思わないです
幸い C# はその他スクリプト系言語とは違って VisualStudio が前提でみたいなもので メモ帳みたいなシンプルすぎるエディタで書くことはまずないです
VisualStudio のおかげでそこまで苦労はしませんでしたが C# の doc comment をそのまま別言語で書きたいかというと そうは思わないです
JavaScript の 「/** */」 よりはマシかなと言う程度です

求める doc comment の言語を探して

書かなくても全く問題ない doc comment で言語を選ぶのは変な話ですが 求める doc comment の言語があるのか気になったので探してみることにしました

まずは TypeScript
マイクロソフト製ですし C# みたいな 「///」 だったりしないのでしょうか……

調べてみたところ JavaScript と同じ 「/** */」 でした
言語外の機能とはいえ JavaScript のスーパーセットというだけあって JavaScript と互換性あるようにしてるみたいです
スーパーセットなら 「///」 にも対応していてもよさそうですけど


PHP (Hack) は JavaScript と同じです
呼び方は PHPDoc

この 「/** */」 の書き方は Java の JavaDoc から来てるようです
Java 嫌いなので 元が Java というのも嫌なところです

Java を改良した C# で 「///」 になったなら JVM 上で Java 改良した言語である Scala や Kotlin はどうなってるのかと調べてみました
結果はどっちも 「/** */」 でした
残念……


elm を見てみると 「{-| -}」 でした
ブロックコメントの記号が違うだけで 「/** */」 に近いです
しかし 複数行にするときに全部の行に 「*」 みたいに 「|」 を書かなくても良いみたいです
JavaDoc 系よりは少しだけ良い感じです


Ruby を見てみると コメント自体は特別な記法ではないようです
普通の 「#」 から始まる行コメントで 引数や返り値の書き方のところだけ決まりがあるようです
ブロックコメントなら 「=begin」 のあとに rdoc と書く必要はあるみたいです
「#」 だとコメントだけを見て判断できないですし コメントの場所で判断してるのかもです

doc comment を特別に目立たせる必要があるかというと 別にない気もしますし これでもいいのかもです
「///」 にしたかったのは 「//」 がコメントと言う前提と doc comment は通常のコメントの記法の中で特別なものと判断できる必要があるという前提だったからです
Ruby は 「#」 コメントですし Ruby のこの書き方でもいいかなと思えました


次は Python です
Python は docstring というちょっと特殊なものです
コメントではなく文字列です
クラスや関数定義の中の最初の文字列が docstring です
言語自体がサポートしてる機能なので外部ライブラリなしでプログラム中で docstring を取得できます

他とは違う独特なものですが ただの文字列値で言語自体の機能という点では好きな方です
ただ 他の doc comment は関数やクラス定義のブロックの前に書くのに対して Python の docstring はブロックの中の最初に書きます
これは良くも悪くもあって慣れるまでは読みづらいですし 慣れてきてもときどき外にある方が見やすいかなと思うことはあります

コメントエリアが長いと引数の受け取りと最初の処理でかなり間が空いてしまいます
折りたたみができないエディタだと引数の確認が面倒です
また色でコメントエリアがわかりやすくなっていないと コメントエリアにコードが書かれてる場合もあって 処理の始まりがどこなのかパッとみてわかりづらいです
反面 インデント的には関数のコメントは関数の中に入ってるので クラス定義内のメソッド一覧を見やすかったりします


そういえば D で 「///」 を見たような見なかったような記憶があるので調べてみました
ブロックコメントでは 「/** */」 と 「/++ +/」 で行コメントでは 「///」 を使うようです
「///」 来ました
C# とは違って 「///」 の中は XML ではなくシンプルに見やすいものです
公式ドキュメントに書かれていたので公式にサポートしてる機能のようです


D で Dart も思い出したので見てみます
Dart も 「///」 と 「/** */」 をサポートしていました
C# スタイルと JavaDoc スタイルと呼んでいます
コンパクトなので 「///」 の方を推奨してるようです
わかってますね! 少しだけ Dart に興味を持ち始めましたよ
Dart も公式ドキュメントに書かれていたので 標準機能のようです


他に最近の言語は…… と考えると Rust がありました
Rust は 「///」 を使うようです
いいですね!
もうひとつ 「//!」 もあって 「///」 は外側に書く用で 「//!」 は内側に書く用みたいです
多くの doc comment みたいなのは 「///」 で Python みたいなものは 「//!」 になるということみたいです
とは言っても内側に書いてるものはほとんどなくて モジュール全体に対しての doc comment をファイルの最初に 「//!」 として書くくらいの使い方みたいです
Rust も公式のドキュメント内に書かれているので標準の機能のようです


Swift も見てみました
「///」 と 「/** */」 のどちらでも良いみたいです
例では 「/** */」 の場合に各行に 「*」 を入れていなかったので入れなくて良いみたいです
公式ドキュメント中には doc comment についての記述が見当たらず別のサイトで見つけたものなので 言語の公式サポートではなく サードパーティ製のライブラリによるものなのかもしれないです

意外とあった

JSDoc のような JavaDoc 系ばかりのように感じてましたが 思った以上に 「/** */」 以外に対応してる言語がありました

Python は変わりどころですが あれはあれでいいと思いますし
Ruby の区別しないのもいいと思います

D/Dart/Rust/Swift は求めていた 「///」 で書けるので 好感度が上がりました
C# は 「///」 だから調べる前では一応一番だったのですが 「///」 なのに XML じゃないのが意外とあって 実は他より使いづらいものでした

Java 系は仕方ないとして JavaScript (TypeScript) や PHP は JavaDoc 系を捨てるか D や Dart のように 「///」 でもいいようにしてほしいですね
一応 JSDoc では本来の目的のドキュメント化するライブラリでは 「///」 を 「/** */」 に置き換えて処理するプラグインがあるので その目的では 「///」 で書いても大丈夫そうです
ただ ドキュメント生成に使うことって全然なくてエディタのサポートや人が直接読む用途がほとんどなので エディタ次第になります

以前の VSCode は JSDoc でない普通のコメントを関数の直前に入れておけば カーソル合わせたときなどにコメントが表示されていたので 普通のコメントで書いてました
ときどき doc comment らしさを出すために 「///」 にしてみたりもしてました
しかし 最近では JSDoc でないコメントは無視されてエディタサポートに使われなくなっています
行 doc comment をサポートしてる言語も多いのですし VSCode 独自でもいいので対応してほしいものですね