サンプルコードの拡張記法を使うべき場面について再考

[yumetodo]

動機

サンプルコードの拡張記法が適応されるべき場面について、/reference以下にあるものについては現状のままでも意義はないと個人的には思っているのですが、/lang以下などについては十分に議論がなされなかったと思っています。

#473 では後述の通り @faithandbrave さんが唐突に

「インクルードとmain関数を含む完全なコードのコードブロック」に対して付ける

という方針を出されて、 #473 がcloseされたのでそれがルールになったわけですが、

cpprefjp/kunai#69

で横道にそれて問題になったのが

https://cpprefjp.github.io/lang/cpp17/remove_deprecated_increment_of_bool.html

にある次の2つのソースコードです。

int main(void)
{
  int flag = 0;
  /* do something */
  if(flag){
    /* do something when flag is true*/
  }
  return 0;
}

#include <iostream>
#include <vector>
int main()
{
  std::vector<int> v{};
  //append elements to v
  int flag = 0;
  for(auto&& i : v){
    if(flag++) std::cout << ',';
    std::cout << i << std::endl;
  }
}

いずれも

「インクルードとmain関数を含む完全なコードのコードブロック」に対して付ける

というルールには合致し、また合法なコードですが、実行されるべきではないと考えます。理由は、前者では変数flag、後者では変数vの状態がどうなっているかわからないことに前提をおいた説明をしたいのであって、実行したところで意味のある出力を産まず、またそうなるように書き換えると説明がわかりにくくなるからです。

サンプルコードの拡張記法の経緯

サンプルコードの拡張記法は、サンプルコードを実行可能にする機能を実装する際に、何を実行可能かを自動判定するのは無理があるということで、 cpprefjp/site_generator#30 で複数のsyntaxが検討された後、CommonMarkに準拠した

```cpp example
int a = 42;
std::string s = "ほげほげ";
```

のような記法が導入することが #473 のCloseを持って決定されました。

これによって
cpp example(書かれていないけど多分 c exampleも対象ですよね？ @saki7 => cpprefjp/kunai#70 )と書かれたコードブロック=実行可能
にすることになりました。

ここまでの議論で出てきたサンプルコードの拡張記法を使うべき場面に関する言及

cpprefjp/site_generator#30 では

cpprefjp/site_generator#30 (comment) by @yumetodo
cpp:exampleというよりcpp:runnableかと。サンプルコードでもコンパイルが通らないものもあるし、コンパイル・実行可能かを示すべきでは

cpprefjp/site_generator#30 (comment) by @saki7
runnable かどうかは定性的に判断できないので、もっとゆるふわな表現の方が僕は好きです。

cpprefjp/site_generator#30 (comment) by @yumetodo
runnableというかwell-formedか。

well-formedか否かは判別できるはず

cpprefjp/site_generator#30 (comment) by @faithandbrave
すいません、ここでの実行可能とは、Wandboxで実行可能、という理解であっていますか？
たとえば今後ネットワークライブラリが入った場合、(DDoSの踏み台にならないように) Wandboxでは動かないようにするのが正しいかと思いますが 、「インクルードとmain関数を含んだ完全なコード」であることと、「Wandboxで動く」ことでは隔たりがあるのではないかと思います。
これは、コード抽出のためのタグ付けと、フロントエンドのWandbox連携のためのコード抽出では、分けて考えておいたほうがいいのでは、という意図です。
単に「実行可能」であることをタグ付けしちゃうと困りそうだなと。

cpprefjp/site_generator#30 (comment) by @yumetodo

すいません、ここでの実行可能とは、Wandboxで実行可能、という理解であっていますか？

それもあって

runnableというかwell-formedか。

と発言しました。

cpprefjp/site_generator#30 (comment) by @saki7
※僕もアキラさんの意見に賛成で、「例」以下のコードブロックで動かないものがあれば、記事側を直した方が良いという認識です。
※つまるところ、 runnableかどうかはこのIssueの範囲では問題にしていないということです。

cpprefjp/site_generator#30 (comment) by @faithandbrave
あまり新ルールを入れると、コントリビューターの参入障壁が上がるのでルールは少ないほうがよい、というのが基本的な考えです。
ですので、cpprefjpに限っては## 例の下にあるcppコードブロックを探せば全てのページで解決できるからパーサーをがんばればよさそう、と思うのですが、これがboostjpを視野に入れたものであればタグ付けは必要かと思います。

cpprefjp/site_generator#30 (comment) by @saki7
僕も site に仕様変更を入れないで済む可能性も含めて色々考えたのですが、仰るように boostjp もできれば綺麗にしたいですし、 cpprefjp の範囲でも article/ 以下の記事は既にサンプルコードの検知で限界が来ています。なので、僕はやはりcpp exampleは必要という結論に至りました。

とその議論はこのIssueの範疇ではないということで議論が途切れて別の話になっています。

ところが

#473 (comment) by @faithandbrave
cpp exampleを書く場所ですが、基本的には「インクルードとmain関数を含む完全なコードのコードブロック」に対して付けます。
例外は、翻訳単位のようなものの説明のために、コードが分割されているようなケースです。

pthreadライブラリのような環境依存のライブラリを使用しているコードであっても、cpp exampleにしてもらって大丈夫です。

とどこからともなく「インクルードとmain関数を含む完全なコードのコードブロック」に対して付けるという方針が出てきました。(当時私は見落としていた)

私が見落としていたとは言え #473 で否定意見が出なかったことは確かなので、ガイドラインとして機能しています。

提案内容

「例」の項に書かれたコードについてはすべて実行可能であるべきだという点については現状のルールの意図するところで、拡張記法導入の経緯の議論からいってもいいと思うのですが、それ以外の項のコードについてはたとえmain関数があってコンパイルが通るものでも編集者のよきように、でいいんじゃないかなと思います。厳密にルールを決めるのは難しいので。

well-formedではないものについては先の議論では否定的な意見でしたが、

cpprefjp/kunai#69 (comment) by @faithandbrave
Wandboxで実行することで、実際にコンパイルエラーになることを確認できるので、それも実行可能にしたほうがよいかと思います。

というのもわからなくはないので、やはりこれも編集者が説明に都合がいいコンパイルエラーが出ていたら実行可能にしてもいいことに、ということで編集者のよきように、でいいんじゃないかなと思います。説明に関係ないエラーが出ることが避けられない場合もあると思うので。

ルール変更時の作業内容

• 編集者向けの細かい慣例を明文化する #481 のreopenとドキュメント再整備

[faithandbrave]

WebページでのWandboxでのコード実行は、ページの読者がサンプルコードをその場で編集していろいろなことを試すことを意図していると理解しています。
実行結果を確認するだけであれば、編集者が記載している出力欄を見れば済みます。

また、exampleタグを付けないことを編集者が意図したものだとして、ほかの編集者が改めて付けた場合、その意図の落としどころをどこにするかが難しい問題となります。その意図をどこかに明示してあれば議論しやすいですが、どこにも意図が書かれていない場合、exampleタグも付いていないことは単に付け忘れと見なすこともできますし、「元の編集者の意図は不明だが、自分は付けるべきだと確信できる」となればそれもexampleタグを付ける理由となるでしょう。
記事を書いた元の編集者の意図が絶対ということはないこともあり、編集合戦になることも避けたいです。

これらのことから、方針はいまと変えるべきでないと私は主張します。

[saki7]

全体的に、難しく考えすぎです。

端的に書くならば、 example タグは基本的に付けてください。

ここで一番日常的に遭遇する例外は、リファレンス記事のトップに記載されているC++規格上のシグネチャのコード片です。これは規格通りであることが重要なために実行も書き換え試行も不必要なので、exampleは付けないでください。

他の例外としては、ページ内で既出のコードの一部分を2回以上参照する目的で抜粋して解説を行う場合などがあります。これの全てをplay可能にする必要性も無いので、全部にexampleタグを付ける必要性はありません。

上記のようなもの以外は、よっぽど特殊な事情が無い限りはexampleは付けて下さい。ここの特殊な事情というのは、僕の認識ではまず出現しません。なので、exampleは基本的に付けてください。

「もしかして付けない方が良いのでは」と記事の編集者本人が感じた時点で、「付いていた方が良いと感じる人」と「付いていない方が良いと感じる人」の両者は絶対に居るので、迷ったらむしろexampleは付けてください。

最後に、これは仮定の話ですが、もし、exampleを付け過ぎたことで実行ツールバーがページ内に大量に出現して見づらくなった場合は、むしろ記事の書き方を直した方が良いと思います。何故なら、閲覧者の感覚として「実行して試してみたい」と思うようなコード片が1ページに何十個も出てくる記事があったとしたら、それは記事の書き方が悪いからです。しかし、そういう記事は今は無いと思います。

---

ここからはyumetodoさんの指摘の細かい点についての僕の認識を書きます。

@yumetodo:

#473 では後述の通り @faithandbrave さんが唐突に

インクルードとmain関数を含む完全なコードのコードブロック」に対して付ける

という方針を出されて、 #473 がcloseされたのでそれがルールになったわけですが、

「サンプルコード」という概念は、 #473 でフロントエンド/バックエンドの実装の都合上 "exampleタグ" という形で出てきただけで、概念自体は #473 で新しく生まれたわけではないです。
@faithandbrave さんが "唐突に" 独断で決めたわけでもありません。

なので、

とどこからともなく「インクルードとmain関数を含む完全なコードのコードブロック」に対して付けるという方針が出てきました。(当時私は見落としていた) (@yumetodo)

これは ”どこからともなく” 出てきた方針ではなくて、cpprefjpに元からあった慣習です。

コード片のうちどのコード片を「サンプルコード」として扱うかという決まり事は、僕がこのコメントの冒頭で書いたように厳密に例外条件などを書こうと思うとキリがないので、今まで明文化されていなかっただけです。 @faithandbrave さんは今までの cpprefjp の慣習上、どのような場所に書かれているコードがplayできたら嬉しいかという「感覚」を知っていると思うので、そういう慣習とか背景を改めて書き下しただけでしょう。

@faithandbrave さんが書き下した感覚というのは、再掲しますが以下の通りです。

#473 (comment)

cpp exampleを書く場所ですが、基本的には「インクルードとmain関数を含む完全なコードのコードブロック」に対して付けます。

この肌感覚は、フロントエンド（kunai）のplayground機能の実装意図とも完全に合っています：

WebページでのWandboxでのコード実行は、ページの読者がサンプルコードをその場で編集していろいろなことを試すことを意図していると理解しています。
実行結果を確認するだけであれば、編集者が記載している出力欄を見れば済みます。
(@faithandbrave)

@faithandbrave さんの上記の説明は、kunaiを作った僕の感覚とまったく同じです。「試したい」とか「試したくなるかもしれない」とか「試したくなるかもしれないしならないかもしれない」とか思った時点で試したいはずなので、 exampleタグは付けてください。

---

もう一度繰り返しになりますが、 exampleタグは基本的に付けてください。これを付けるかどうか迷って執筆に支障が出るようなら @e-kwsm さんなども右記コメントで仰っているように明文化した方が良いと僕も思いますが、喫緊の問題ではないと思います。参照： #481 (comment)

明文化したいということであれば、執筆者向けページに追記する形が良いと思うので、PRを投げてください。そのPRがcpprefjpの現状の肌感覚に即しているという同意がPR上で得られれば、僕がマージします。

---

結論としては、 @faithandbrave さんが書いている通り、方針は変えません。

@e-kwsm さんからexampleタグの追加漏れのPRが上がっていますが、これは有用なのでマージします。

[yumetodo]

WebページでのWandboxでのコード実行は、ページの読者がサンプルコードをその場で編集していろいろなことを試すことを意図していると理解しています。

ユーザーにいじらせやすくしておく、ということですか。なるほど。

編集合戦になることも避けたいです。

現状Wikipediaでいう半保護状態なのでそうそう編集合戦にはならないとは思うんですが、分かりました。

「サンプルコード」という概念は、 #473 でフロントエンド/バックエンドの実装の都合上 "exampleタグ" という形で出てきただけで、概念自体は #473 で新しく生まれたわけではないです。
@faithandbrave さんが "唐突に" 独断で決めたわけでもありません。

これは ”どこからともなく” 出てきた方針ではなくて、cpprefjpに元からあった慣習です。

コード片のうちどのコード片を「サンプルコード」として扱うかという決まり事は、僕がこのコメントの冒頭で書いたように厳密に例外条件などを書こうと思うとキリがないので、今まで明文化されていなかっただけです。 @faithandbrave さんは今までの cpprefjp の慣習上、どのような場所に書かれているコードがplayできたら嬉しいかという「感覚」を知っていると思うので、そういう慣習とか背景を改めて書き下しただけでしょう。

そういう概念が存在したという認識がなかったもので、それは失礼しました。

しかしそういうことならなおさら @saki7 さんのコメントの要約なりをIssueではないどこか(ドキュメント)に書いていただかないと、このsyntaxの意図するところが新規参加する誰にも伝わりません。
何回か編集するうちにわかる、というのは一般論としてはわからなくはないのですが、この件は記事編集時にコードをどのように説明に使うか、ということに関わります。新規立項したことがない編集者が新規立項する際(そうでなくてもコード片を付け加えるような編集をする時)に知っていると知らないではコード片を記事中への折り込み方なんかに差が出るのではないでしょうか？

[yumetodo]

すみません、 9fd0314 で一つexample tagを外しました。

これは現状複数ファイルの実行をサポートしていないからです。またmingw上じゃないとありがたみがないという話もあります。mingw上でWandboxが実行できる&&kunaiでサポートする日が来たらrevertしてください

[saki7]

しかしそういうことならなおさら @saki7 さんのコメントの要約なりをIssueではないどこか(ドキュメント)に書いていただかないと、このsyntaxの意図するところが新規参加する誰にも伝わりません。
何回か編集するうちにわかる、というのは一般論としてはわからなくはないのですが、この件は記事編集時にコードをどのように説明に使うか、ということに関わります。新規立項したことがない編集者が新規立項する際(そうでなくてもコード片を付け加えるような編集をする時)に知っていると知らないではコード片を記事中への折り込み方なんかに差が出るのではないでしょうか？

分かりました。コードを書く可能性のある全ての雛形の本文中に、コメントとして追記してください。追記する内容としては、僕はもともと説明が必要ないと思っていた側なので僕が書くとよくないと思うので、 @yumetodo さんにお願いしたいです。

僕の希望としては、以下の点が守られていれば細かい文面は任せます。

• 3行以内であること
• 「exampleタグは基本的に書いてください」という趣旨が明文化されていること
• exampleタグを書かない例外の条件などを細かく説明することは避けること

[saki7]

すみません、 9fd0314 で一つexample tagを外しました。 (@yumetodo)

このexampleを外す意図は分かります。この修正は適切だと思います。ありがとうございます。

[saki7]

ああ、上記の追記（方針の明文化）については、直接コミットせずにPRとして投げて頂けると助かります。

[faithandbrave]

こちら、完了しているという認識なので閉じます。