コードブロックの見出し「例」は必要ではないと思う

[universato]

どこかのIssueかPRの議論で、コードブロックの見出しがあった方がいいというやりとりを見た記憶があります。
しかし、書いた方がいい理由が、#@samplecodeブロックの記法が登場する前の話だったように思います。

自分としては、コードブロックの見出しの「例」はない方がいいと考えます。

• 「例」であることは自明で、ない方がシンプル。
• ブロックの見出しがあると、1ページあたりで見れる行数が減る。1回で1行分より多く減っていた記憶です。

[scivola]

「例」をつけるかどうかの議論は #523 ですね。
私はいまのところ，どちらがよいか，はっきりした意見がありません。
もう一度議論して論点を整理し直すのはよいことかもしれません。

[universato]

それですね。ありがとうございます。

よりいうと2017年8月26日のsho-hさんのコメントです。

確かにサンプルであることは自明かと思いますので、「例」を書くかどうかというよりも分けて表示されてほしいという感じです。例えば文章が間に挟まれるなら「例」なしでも気になりません。

ここでsho-hさん自身も、分けて表示されてコードのブロックであることがわかりやすくなるために「例」を書いて欲しいと言っており、#@samplecodeの記法が導入されたことにより「例」をわざわざ書くメリットはないのではと思います。

ここにガイドラインがあるんですね。
rurema/doctree Wiki: SampleCodeGuideline#体裁

各サンプルの先頭に例:の文言を記載してください
複数のサンプルを続けて記述する場合は、各サンプルごとに例:を記載してください