6

英語版 Stack Oveflow でヘルプページ「最小限の・自己完結した・確認可能なサンプルコードの書き方」が変更されたことを日本語版でどう扱うか議論した結果、同じような改定に追従する必要性は小さいものの、現状のヘルプページは書き直して良いのではないかという話になりました

特に以下の点が気になります。

  • タイトルがやや長い。
  • 日本語として微妙な部分がいくつかある。

そこで、現状の内容を回答に転載しますので、どこをどう変えるか編集・コメントしてください。個別の意見があれば回答として投稿してください。回答に対する投票やコメントで議論したいです。

参考 (英語版): https://stackoverflow.com/help/minimal-reproducible-example

3
  • 1
    参考:本家SOで質問のコメント欄にアドバイスとして貼られているのを見かけました。「ここを改善すると回答が得られやすいよ」というアドバイスをFAQとしてまとめているみたいです。 - idownvotedbecau.se
    – cubick モデレーター
    Commented 2019年5月21日 8:13
  • 1
    参考:私はよくこちらを参考にしています - 技術系メーリングリストで質問するときのパターン・ランゲージ
    – nekketsuuu モデレーター
    Commented 2019年5月21日 9:21
  • 1
    前の投稿に書かれたヘルプページの差分と今の日本語訳を見るに、英語版ではこれ以外にも中身が変わっているのではないかという気がしてきました。以前のバージョンの対訳になっていません。
    – nekketsuuu モデレーター
    Commented 2019年5月24日 2:15

2 件の回答 2

5

コミュニティwikiとして投稿しておきますので、必要ならこちらを直接編集してください。
もちろん個別の提案等があれば別回答を投稿してもらって構いません。


再現可能な短いサンプルコードの書き方

質問をする際、第三者が質問の内容を理解し、手元で問題を再現できるような良いサンプルコードを含めると、より良い回答をもらいやすくなります。この「良いサンプルコード」を作るための条件がいくつかあります:

  • 短くテキストで:できるだけコードを削った上で、同じ問題が出るようにする。
  • 自己完結している:問題を再現するために必要なコードとデータを漏れなく書く。
  • 再現可能である:投稿する前にサンプルコードを実行してみて、問題が再現するかどうかを確認する。

このページでは、どうやって「良いサンプルコード」を作るかの方法を説明します。

短いこと

確認しなければいけないコードの量が多くなればなるほど、問題の原因を見つけにくくなります。コードの分量を小さくしましょう。サンプルコードを減量するにはふたつのやり方があります:

  1. いちから作り直す:プログラムを新規作成し、問題を再現するのに必要な部分のみを追加していきましょう。関数や変数の名前は、用途がシンプルに説明されているものにしましょう。
  2. 各個撃破する:自分のコードのどこに問題があるか分からない場合、まずはその問題が生じなくなるまでコードを少しずつ削ってみましょう。最後に削った部分が問題の箇所です。

いちから作り直す方法は、実際のコードを契約上の理由などで公開できない場合にも有効です。

短く、ただし読みやすく

短くといっても、読みやすさや伝わりやすさは大事にしましょう。命名規則とインデントを統一し、必要に応じてコメントも含めてください。大抵のエディタでは自動的にコードを整形する機能があります。使い方を覚えてぜひ利用しましょう!

また、タブ文字の代わりに空白文字を使いましょう。エディタ上では綺麗に見えても、スタック・オーバーフロー上ではきちんと揃った表示にならないことがあります。

自己完結していること

問題を再現するのに必要な情報が質問自体にすべて入っているかを確認しましょう。

  • 問題を再現するのに、XMLの設定ファイルなどサーバー側のコードが必要なのであれば、それも質問文に含めてください。ウェブ系の問題でHTML・JavaScript・CSSが関わっているなら、3つ全て含めてください。問題の原因はあなたの思っているコード以外の部分かもしれません。
  • それぞれのファイルやコード断片を分けて表示するため、個別のコードブロックを使ってください。あわせて、それぞれのブロックに説明を書きましょう。
  • HTML・JavaScript・CSSを全て含めるには、エディタのスニペット機能を使うのが便利です。
  • コードのスクリーンショットを使うのは避けましょう。実際のコードをテキストのままコピー&ペーストし、エディタのコード自動整形機能を使ってください。こうすることでコードが読みやすくなり、また第三者が手元で試しやすくなります。

再現可能であること

問題解決への第一歩は、まずどんな問題なのかを確認することです。他の人が確認できるよう、以下のことに気をつけましょう。

  • 問題をきちんと説明しましょう:「うまくいかない」だけでは問題を説明したことになりません。どういう動作を期待していますか? エラーメッセージを一字一句、どのファイルのどの部分で発生しているか教えてください。質問のタイトルには、どんな問題かが分かるような要約を書いてください。
  • 関係のないエラー・警告は排除しておきましょう:コンパイラのエラーについての質問ではないのなら、コンパイル時点でのエラーが出ないようにしておきましょう。あるいはJSLint等で書き方が正しいことを確認してください。HTMLやXMLも記述に問題が無いかバリデーションチェックで検証しましょう。
  • サンプルコードで実際に問題が再現するかを確認しましょう:サンプルコードを作っている間に問題が消えてしまうことがあります。投稿前に手元でもう一度実行し、問題が再現することを確かめてください。

問題を再現できることを確認するには、システムを再起動したり、他の新しい環境に持っていったりなどして試した方がいい場合もあります。

2
  • 1
    例がなぜかHTML関連なのが気になる。もっとプログラム寄りな「ヘッダファイルやライブラリの名称も含めよう」等の方がイメージしやすい?
    – cubick モデレーター
    Commented 2019年5月21日 8:10
  • 1
    英語版に合わせて情報を色々と追加しました。また、英語版だとスニペット機能の部分にリンクが張ってあったものの、これの日本語版が無かったので省略しています。同様のメタ記事を日本語版に作って良いかもしれません。
    – nekketsuuu モデレーター
    Commented 2019年5月24日 2:49
2

最近何件かスクリーンショットで質問されたのが気になったので、少し目立つように案を考えてみました。あとテストデータの記述も増やしてみました。
太字にしたのは追記部分を明確にするためで、実際の記述時には適用しません。


独立した行で項目を増やす方式:

  • 短い:できるだけコードを削った上で、同じ問題が出るようにする。
  • テキストで:スクリーンショットは避けて、テキストで書く。
  • 自己完結している:問題を再現するために必要なコードを漏れなく書く。
  • テストデータも:同じく再現するために必要なデータも漏れなく書く。
  • 再現可能である:投稿する前にサンプルコードを実行してみて、問題が再現するかどうかを確認する。

現在の内容に追記する方式:

  • 短く テキストで :できるだけコードを削った上で、同じ問題が出るようにする。
  • 自己完結している:問題を再現するために必要なコード とデータ を漏れなく書く。
  • 再現可能である:投稿する前にサンプルコードを実行してみて、問題が再現するかどうかを確認する。

スクリーンショットを避ける説明は選択した方式に合わせて現在の説明を移動や単独化する。
ちなみに英語版では以下のように多数の理由をまとめた記事が紹介されていました。
Why not upload images of code/errors when asking a question?

データについては、以下のような要領の説明を記述すれば良いでしょう。

  • コードと同様に、問題を再現するために必要な最小限のデータをテキストで漏れなく書く。
    (ちなみに実際はカンマ区切りなのに質問では空白区切りで書かれていたこともあったので、記述は正確にしてもらう)
  • テキストに出来ない(あるいは滅多に無い特殊な形式の)イメージ等は1~2個なら質問に添付。
  • 必要だが質問に書くと膨大になるなら入手方法やテスト時の配置方法を記述しておく。

この質問に回答するには、ログインする必要があります。

求めていた回答ではありませんか? のタグが付いた他の質問を参照する。