自己文書化コード

コンピュータプログラミング において、自己文書化（または自己記述型）ソースコードとユーザーインターフェースは、命名規則と構造化プログラミング規則に従っており、事前の特定の知識がなくてもシステムを使用できます。^[1] Web開発において、自己文書化とは、公開文書を通じて作成プロセス全体を公開し、その公開文書が開発プロセスの一部であるWebサイトを指します。^[要出典]

自己文書化システムの一般的な目的は次のとおりです。

• ソースコードを読みやすく理解しやすくする^[2]
• レガシーシステムの維持や拡張に必要な労力を最小限に抑える^[2]
• システムのユーザーや開発者がコードコメントやソフトウェアマニュアルなどの二次文書を参照する必要性が減る^[2]
• 自己完結型の知識表現を通じて自動化を促進する

自己文書化コードは、表面上は人間が読める名前を使用して記述され、通常はarticle.numberOfWordsやTryOpenなど、シンボルの意味を反映する人間の言語のフレーズで構成されます。また、人間の読者が使用されているアルゴリズムを簡単に理解できるように、コードは明確でクリーンな構造になっている必要があります。

自己文書化システムの目的が実現できるかどうか、またどの程度実現できるかに影響を与える、いくつかの実際的な考慮事項があります。

• 命名規則の統一^[2]
• 一貫性^[2]
• アプリケーションの範囲とシステム要件

以下は、明示的なコメントの代わりに命名規則を使用してコードのロジックを人間の読者にとってより明確にする、 自己文書化Cコードの非常に単純な例です。

size_t count_alphabetic_chars ( const char * text ) { if ( text == NULL ) return 0 ;   

       
         

    size_tカウント= 0 ;    

    while ( * text != '\0' ) { if ( is_alphabetic ( * text )) count ++ ; text ++ ; }   
    
         
            
        
    

    カウントを返す; } 

ジェフ・ラスキンは、コードではプログラムがなぜ書かれているのか、なぜそのように実装されているのかという根拠を説明できないとして、「自己文書化」コードに対する信念を批判した。^[3]

• 自称語
• コードの可読性
• コメント（コンピュータプログラミング）
• 制御された自然言語
• リテラルプログラミング
• 自然言語プログラミング

• McConnell、Steve。「高品質ルーチンのチェックリスト」。Code Complete。