質問: 英語版 Stack Oveflow でヘルプページ「最小限の・自己完結した・確認可能なサンプルコードの書き方」が変更されたことを日本語版でどう扱うか議論した結果、同じような改定に追従する必要性は小さいものの、現状のヘルプページは書き直して良いのではないかという話になりました。 特に以下の点が気になります。 * タイトルがやや長い。 * 日本語として微妙な部分がいくつかある。 そこで、現状の内容を回答に転載しますので、どこをどう変えるか編集・コメントしてください。個別の意見があれば回答として投稿してください。回答に対する投票やコメントで議論したいです。 参考 (英語版):
回答: コミュニティwikiとして投稿しておきますので、必要ならこちらを直接編集してください。 もちろん個別の提案等があれば別回答を投稿してもらって構いません。 再現可能な短いサンプルコードの書き方 ================== 質問をする際、第三者が質問の内容を理解し、手元で問題を再現できるような良いサンプルコードを含めると、より良い回答をもらいやすくなります。この「良いサンプルコード」を作るための条件がいくつかあります: * 短い:できるだけコードを削った上で、同じ問題が出るようにする。 * 自己完結している:問題を再現するために必要なコードを漏れなく書く。 * 再現可能である:投稿する前にサンプルコードを実行してみて、問題が再現するかどうかを確認する。 このページでは、どうやって「良いサンプルコード」を作るかの方法を説明します。 短いこと 確認しなければいけないコードの量が多くなればなるほど、問題の原因を見つけにくくなります。コードの分量を小さくしましょう。サンプルコードを減量するにはふたつのやり方があります: 1. **いちから作り直す**:プログラムを新規作成し、問題を再現するのに必要な部分のみを追加していきましょう。関数や変数の名前は、用途がシンプルに説明されているものにしましょう。 2. **各個撃破する**:自分のコードのどこに問題があるか分からない場合、まずはその問題が生じなくなるまでコードを少しずつ削ってみましょう。最後に削った部分が問題の箇所です。 いちから作り直す方法は、実際のコードを契約上の理由などで公開できない場合にも有効です。 ### 短く、ただし読みやすく 短くといっても、読みやすさや伝わりやすさは大事にしましょう。命名規則とインデントを統一し、必要に応じてコメントも含めてください。大抵のエディタでは自動的にコードを整形する機能があります。使い方を覚えてぜひ利用しましょう! また、タブ文字の代わりに空白文字を使いましょう。エディタ上では綺麗に見えても、スタック・オーバーフロー上ではきちんと揃った表示にならないことがあります。 自己完結していること 問題を再現するのに必要な情報が質問自体にすべて入っているかを確認しましょう。 * 問題を再現するのに、XMLの設定ファイルなどサーバー側のコードが必要なのであれば、それも質問文に含めてください。ウェブ系の問題でHTML・JavaScript・CSSが関わっているなら、3つ全て含めてください。問題の原因はあなたの思っているコード以外の部分かもしれません。 * それぞれのファイルやコード断片を分けて表示するため、個別のコードブロックを使ってください。あわせて、それぞれのブロックに説明を書きましょう。 * HTML・JavaScript・CSSを全て含めるには、エディタのスニペット機能を使うのが便利です。 * コードのスクリーンショットを使うのは避けましょう。実際のコードをテキストのままコピー&ペーストし、エディタのコード自動整形機能を使ってください。こうすることでコードが読みやすくなり、また第三者が手元で試しやすくなります。 再現可能であること 問題解決への第一歩は、まずどんな問題なのかを確認することです。他の人が確認できるよう、以下のことに気をつけましょう。 * **問題をきちんと説明しましょう**:「うまくいかない」だけでは問題を説明したことになりません。どういう動作を期待していますか? エラーメッセージを一字一句、どのファイルのどの部分で発生しているか教えてください。質問のタイトルには、どんな問題かが分かるような要約を書いてください。 * **関係のないエラー・警告は排除しておきましょう**:コンパイラのエラーについての質問ではないのなら、コンパイル時点でのエラーが出ないようにしておきましょう。あるいはJSLint等で書き方が正しいことを確認してください。HTMLやXMLも記述に問題が無いかバリデーションチェックで検証しましょう。 * **サンプルコードで実際に問題が再現するかを確認しましょう**:サンプルコードを作っている間に問題が消えてしまうことがあります。投稿前に手元でもう一度実行し、問題が再現することを確かめてください。 問題を再現できることを確認するには、システムを再起動したり、他の新しい環境に持っていったりなどして試した方がいい場合もあります。