初心者向けのプログラミングに関する記事の書き方

最近、「初心者」向けの記事として位置付けられているプログラミングやその他の側面について、かなりの記事がHabréに登場し始めました。 一方、初心者にとっては、これらの記事は理解できないことがよくあります。複雑すぎる場合もあれば、必要な質問に答えない場合もあり、理解しにくい場合もあります。



記事が好かれているだけでなく、読者にも役立つようにしたい場合は、記事の書き方を考えてみましょう。

ターゲットオーディエンスを定義する

ターゲットオーディエンスを定義することから始めます。 「初心者」の概念は非常にあいまいです。 「初心者」と呼ばれることができる完全に異なるカテゴリーの人々を以下に示します。

• プログラミングのことをまったく聞いたことがなく、コードの書き方を学びたい人。
• 理論的基礎（コンパイラが行うこと、コンパイルと解釈の違い、コードの記述プロセスが行うこと）のいくつかを知っているが、自分でコードを書いたことがない人
• プログラミングに携わっているが、わずかに異なるプロファイルに切り替えたい人（たとえば、単純なWebサイトを入力してjavascriptを知っているが、デスクトップアプリケーションの作成方法を学びたい人）
• 最後に、プログラミングにかなり精通しているが、自分で新しい言語や技術を学びたい人。

さまざまなレベルの人を対象とした記事がまったく異なって見えることは明らかだと思います。 ただし、「初心者向け」とマークされているほとんどの記事は、表面的にプログラミングに精通している人を対象としています。

記事を理解するために必要な基本的な知識を特定します。

同意します。最初から次のように書くのはそれほど難しくありません。

「この記事を理解するには、読者はCの初期知識が必要です。

-アプリケーションをコンパイルして実行できる

-構文、基本的なデータ型、管理構造を知っている”

それほど時間はかかりませんが、読者を大いに助けます。 このような記事を始めるなら、私を信じてください：

次のコードをコンパイルします。

int main(int argc, char *argv[]) { cout<<"Hello, world!"; }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

読者は彼らに何が必要なのか全く理解できないかもしれません。 コンパイラの使用方法がわからない場合は、忘れないでください。

記事をできるだけ良くする

優れた有能なデザインは、素材を簡単に理解するための鍵の1つです。

コード全体を書き込もう

コードが別々に与えられた記事や本を見ました。 これは、読者がコードを簡単にコピーして実行できないという事実は言うまでもなく、コードを理解するのが難しいという事実につながります。 もちろん、例えば、異なるリストに異なる関数を書くことができます。 これは理解を容易にするので、さらに良いです。 ただし、論理的に同種のコードを分解しないでください。



このように書かないでください：

「Hello、World」を表示するサンプルプログラム：

 //   int main(int argc, char *argv[]) { cout<<"Hello, world!";
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

一部（おそらく非常に便利）

著者からの複数行コメント

 // return 0; }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

このように書く：

「Hello、World」を表示するサンプルプログラム：

 #include <iostream> using namespace std; int main(int argc, char *argv[]) { cout<<"Hello, world!"; return 0; }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

ここでは、長く詳細なコメントを書くことができ、さらにその行をもう一度書くこともできます

 cout<<"Hello, world!";
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

彼が言及している。

コードを複数のリストに分割する必要がある場合は、記事の最後でもう一度、すべてのコードを1つのリストにリストするか、このコードをダウンロードできるリンクを提供してください。

記事に挿入する前に、必ずコードを確認してください。

読者は座って、記事の例がうまくいかない理由を理解しようとしません。

同じ理由で、コードが何らかの方法で環境またはコンパイラに依存する場合は、これを個別に指定します。

コードを常にコメントする

単一のコメントのない本で3ページのリストがどのように見つけられるか、何百万回も見てきました。そして、全文でこのコードが何をするかの説明です。 そのようなことは非常に読みにくいです。 コード自体に短いコメントを書いてみてください。

 #include <iostream> //   cout using namespace std; //cout     std int main(int argc, char *argv[]) { cout<<"Hello, world!"; //  "hello, world" return 0; }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

文字列の値が明らかな場合、これは誰にとっても明白であることを意味しないことを忘れないでください。 コードについて詳しくコメントしたい場合は、行番号を挿入することをお勧めします。 行内のすべての行に番号を付ける必要はありません。これを行うだけです：

 1 #include <iostream> using namespace std; 4 int main(int argc, char *argv[]) { 6 cout<<"Hello, world!"; return 0; }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

1行目には、C ++でストリーミングI / Oを操作するために必要なクラス、関数、および変数を含むヘッダーファイルが含まれています。 標準出力ストリームであるcoutオブジェクトを使用するために、このファイルを含めます。



4行目で、メイン関数が始まります-この時点から、プログラムの作業が始まります。



最後に、 6行目で「Hello、world」というフレーズを標準cout出力ストリームに出力します。 これには<<演算子を使用したかなり単純な構文が使用されます。 演算子の左側にはストリームオブジェクト（この場合はcout）が書き込まれ、右側にはこのストリームに出力される式が書き込まれます。

読者がコードをコピーして実行できるようにしたい場合は、コメントに行番号を指定できますが、これはそれほど明白ではありません。

 #include <iostream> //(1)    cout using namespace std; //(2) cout     std int main(int argc, char *argv[]) { cout<<"Hello, world!"; //(6)   "hello, world" return 0; }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

読者の立場に身を置く

あなたの例のどの場所があまり明確ではないかもしれないと想像し、それらをより詳細に説明してください。 インターネットや書籍で見つけやすいものを説明するのが面倒な場合は、それについて読むことができるリソースへのリンクを提供してください。

コードを複雑にしすぎず、完璧主義を避けてください

初心者向けの記事を書いていることを忘れないでください。 コードをよりシンプルにできる場合は、それを行う方が良いでしょう。 コードが（より複雑になっても）改善できることを示したい場合は、簡単な解決策の後に記述してください。 returnステートメントがどのように機能するかを人に説明しているとします。たとえば、2つの数値を比較して最大（または数値が等しい場合は任意）を返す関数を作成することにしました。 のようなものを書かないでください

 template<class T> T compare(T a, T b) { return a>b?a:b; }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

シンプルで明確なコードを記述します。

 int compare(int a, int b) { if(a>b) { return a; } else { return b; } }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

10倍改善してみましょう-特定の実装ではなく、メソッドの本質を示すことがタスクであるかどうかは関係ありません。

記事全体を通して同じレベルに固執するようにしてください。

基本レベルで記事を書き始め、簡単なことについて詳しく話し始めたら、記事の最後までこれを行ってください。 記事の途中で突然説明をやめた場合、読者は記事のスレッドを完全に失い、混乱する可能性があります。

記事全体を通して同じスタイルに固執する

「アカデミック」スタイルで書くか、「今、男、私たちが創造物を編集する」スタイルで書くかは関係ありません。 一貫性があり、記事ごとに正式なものから非公式なものへと10回戻ることのないようにすることが重要です。

あなたの考えを構造化してみてください

あなたはプログラミングについて話している-それはあなたの物語が重要な部分に簡単に分割される可能性が最も高いことを意味します。 構造化された記事は読みやすく、理解しやすいため、常にこれを行うようにしてください。 テキスト自体がかなり単純なことを語っている場合でも、しっかりしたテキストの壁を把握することは非常に困難です。

読者を助けるようにしてください。

コメントに礼儀正しくしてください。 何かをより詳細に説明するか、記事に何かを追加するように求められたら、それを試してみてください（もちろん、時間とエネルギーがあれば）。

おわりに

私の記事が、著者が記事をより理解しやすくし、その結果、より一般的になるのに役立つことを願っています。 ポイントに同意しない場合、または独自の何かを追加したい場合は、コメントを記入してください。