ハイパーリンクされ、外部化されたソースコードのドキュメント[終了]

別のドキュメントとしてではなく、なぜソースコードの自然言語記述（つまり、コード行が記述された理由）をソースコード内に埋め込むのですか？

現代の開発環境（高解像度モニター、デュアルモニターなど）に提供される広大な不動産を考えると、IDEは、ソースコードが視覚的に分離されているが本質的にリンクされているセミロックステップパネルを提供できます。対応するコメント。たとえば、開発者はハイパーリンクマークアップ言語（追加のソフトウェア要件へのリンク）でソースコードコメントを書くことができます。これにより、ドキュメントがソースコードを乱雑にするのを同時に防止できます。

このようなソフトウェア開発メカニズムを阻害する欠点は何ですか？

質問を明確にするためのモックアップ：

カーソルがソースコードの特定の行（上記の青色の背景で表示）にある場合、カーソルのある行に対応するドキュメントが強調表示されます（他の詳細と区別されます）。質問で述べたように、カーソルがソースコード内を移動するとき、ドキュメントはソースコードとロックステップのままです。ホットキーで「ドキュメントモード」と「開発モード」を切り替えることができます。

潜在的な利点は次のとおりです。

• 画面上のソースコードとドキュメントの同時表示
• （言語に関係なく）ソースコードとは関係なくドキュメントを編集する機能
• マージの競合なしに、ドキュメントとソースコードを並行して作成する
• 優れたテキスト形式のリアルタイムハイパーリンクドキュメント
• さまざまな自然言語への準リアルタイム機械翻訳
• コードのすべての行は、タスク、ビジネス要件などに明確にリンクできます。
• ドキュメントは、コードの各行が記述されたときに自動的にタイムスタンプを付けることができました（メトリック）
• アーキテクチャ図、関係を説明する画像などを動的に含める
• 単一ソースのドキュメント（ユーザーが手動で含めるためのタグコードスニペットなど）。

注意：

• ドキュメントウィンドウは折りたたむことができます
• ソースファイルを表示または比較するワークフローは影響を受けません
• 実装がどのように行われるかは詳細です。ドキュメントは次のようになります。
  • ソースファイルの末尾に保持されます。
  • 規則（filename.c、filename.c.doc）で2つのファイルに分割します。または
  • 完全にデータベース駆動
• ハイパーリンクされたドキュメントとは、外部ソース（StackOverflowやWikipediaなど）および内部ドキュメント（つまり、ビジネス要件ドキュメントを相互参照できるサブドメイン上のWiki）およびその他のソースファイル（JavaDocsに類似）へのリンクを意味します。

関連スレッド：業界のドキュメントに対する嫌悪感とは何ですか？

この問題はいつも私を悩ませており、私たちがこれから試して解決するべき方向についてのアイデアを得ました（それでこの質問を見つけました）。

ユーザードキュメントをソースコードに含めることにしたとき、リンクされたドキュメントの問題は間違っていたと思います。doccoのように。

まず、コードのコメントとユーザードキュメントを区別します。

コードのコメントは通常、短い、実際は非常に短い場合に最高です。そのため、なぜ、どのように機能するかについての詩を見なくても、実際にコードを読み取ることができます。

ユーザーコメントは、ライブラリ/ APIを使用しようとするユーザーを対象としており、使用例、そのように実装された理由の説明、またはライブラリの拡張方法の説明が含まれる場合があります。この種のコメントは本当に冗長になる傾向があります。

ドキュメントはプレーンテキストで記述する必要があるため、ベンダーによる修正がなく、VCSに簡単に追加できることに同意します。しかし、ユーザードキュメントをソースファイルに保持することは、少なくとも次の2つの理由から大きな間違いだったと思います。

• コードが読みにくい
• 十分に柔軟なドキュメントではありません（同じサンプルコードを使用する2つのドキュメントページが必要か、2つの異なるソースファイルからコードをインターリーブする必要がある1つのドキュメントページがあるとします）。

では、なぜ同じファイルに入れたいのでしょうか？まあ、誰も自分のドキュメントをコードと同期させたくありません。しかし、とにかく私たちはそれを行い、特にMarkdownの大成功を収めた今日は特にそうです。これは正しい道だと思いますが、足りない場合はかなり短いです。

コードコメントとユーザーコメントをインターリーブすると、2方向のバインディングが作成されます。これにより、どのコメントがコードのどの部分に対応するかを簡単に確認できます。ドキュメントに記載されていないコードがあるかどうかも確認できます。それが提供していないのは、コメントが更新されているかどうかを確認する方法です。これは、コードが読みにくい場合に多く発生します（ドキュメントが醜いため）。

2方向のバインディングではなく、1方向のバインディングがある場合はどうなりますか？コードを指すドキュメント。次のような特別なコマンドを含むマークダウンコードを作成できます。

Some documentation right here that explains the following code:
   @include_file <path/to/some/file>:<line_start>-<line_end>
or
   @include_file <path/to/some/file>
     @starts_with "some regexp or literal text to search"
     @ends_with "another regexp"
or
   @include_file <path/to/some/file>
     @class MyClass
     @method foo
or any combination or way of linking you could imagine

We can even have semantic in the directives:
   @explain_code <path/and/same/of/above>
   @example_code <path/and/same/of/above>
   @performance_notice <path/and/same/of/above>

Which would do basically the same, but it adds the intention of why
do we want to add this code in the first place, which could be 
used different by an IDE. 

これには、いくつかの追加機能を備えたマークアップであるという利点があります。適切なツールを使用すると、さらに多くの価値を追加できます。

（ウオッチタスクでも）gruntのようなツールを使用してこの一方向バインディングを想像してください。ソースファイルの変更を検出し、それに依存するドキュメントファイルを確認し、コメント化されたコードに変更があった場合にユーザーに警告（またはどこかにマークアウト）できます。

404-ページが見つかりません

コードを操作するとき、コメントが失われるのは望ましくありません。これは、コードとコメントを別々のドキュメントに分けるとどうなるかです。

また、コメントドキュメントとコードドキュメントの間でバージョン管理を維持すると、さらに痛みが生じます。

あなたが私が本当に気に入っている提案のいくつかは、コードとコメントを1つのファイルに入れながら、簡単に実装できました。

私が見る可能性のある欠点：

• この機能を実装する特別なエディターが必要です

• コードはもはやプレーンテキストではなく、操作が簡単でVCS-esにコミットできます

• コードを操作するには、画面幅が2倍必要です

あなたの議論については：

画面上のソースコードとドキュメントの同時表示

ただし、2つのファイルを並べて表示する場合は不便です。

（言語に関係なく）ソースコードとは関係なくドキュメントを編集する機能

それは実際には不利だと私は主張します。個人的には、ドキュメントが古くならないように、できるだけコードに近づけるようにしています。

マージの競合なしに、ドキュメントとソースコードを並行して作成する

繰り返しますが、おそらく不利です。あなたのドキュメントがコードで深くインターリーブされている場合、どうすればそれらを個別に編集できますか？

優れたテキスト形式のリアルタイムハイパーリンクドキュメント

コード内にある場合、それはすでにリアルタイムです;）ハイパーリンクに関しては、ほとんどのIDEで定義へのジャンプがすでに実装されています。

さまざまな自然言語への準リアルタイム機械翻訳

なぜ通常のコメント/ドキュメント文字列ではそれができないのか分かりません。

コードのすべての行は、タスク、ビジネス要件などに明確にリンクできます。

これについてはよくわかりません...定期的なコメントで達成できないのでしょうか？

ドキュメントは、コードの各行が記述されたときに自動的にタイムスタンプを付けることができました（メトリック）

VCS-esはすでにこの種の情報を提供していませんか？

そうは言っても、レイアウト自体はとても気に入っています。ただし、ファイル形式を変更する必要はないと思います。通常のコメントから生成することはそれほど難しくありません。それを行うドキュメントジェネレーターがたくさんあります。たとえば、Doccoやその後継のPyccoやMarginaliaなどです。

まず、ドキュメントのコメントはコードと一緒に使用する必要があります-それらを他の場所に移動すると、実質的にゼロの利益を得るために処理が非常に困難になるだけです。なぜわざわざ！

しかし、できることは、埋め込まれたコメントを取り込んでエディターで非表示にし、必要に応じてバブルまたはツールチップなどでそれらを表示することです。私はそのようなアプローチが人々にコードへのより多くのドキュメントを書くことを奨励することを望みます-例えば、クラスの記述は外部の設計ドキュメントではなくクラスと一緒に行くことができます。

現在、コードコメントにハイパーリンクを埋め込むことができ、DoxygenやSphinxなどのツールを使用してコードからドキュメントを生成できます。これらのツールをより適切にサポートするには、コードエディターにちょっとした拡張機能が必要だと思います。

コード行をバグトラッカーや要件ツールにリンクしないので、SCMの方が適しています。次に、タスクにリンクされているコミットごとのコード編集を確認できます。コードに格納されているドキュメントをバグトラッカーに対して統合するつもりはありません。新しいものに移行したい場合（うーん、この機能が現在TFSに追加されているのがわかります）、またはコミット履歴が失われました（これが起こります）

@Bogdanがすでに述べていることに加えて、いくつか追加します。

• 常に2つのファイルが同時に存在するようにIDEを構成しました。あなたが提案している機能を使用すると、同じ量の情報を表示するには基本的に2つのモニターが必要で、2で現在実行していることを実行するには3つ必要です。
• ファイルを参照している間、コメントはすぐには表示されません。探しているものが正確にわからない場合、ファイルを見つけるのは非常に困難です。
• ファイルを検索している間、コメントを直接（または簡単に）検索することはできません。
• sshを使用して、ライブサーバーでさまざまなテストを実行したり、短いコードを記述したりする必要がある場合があります。あなたが言っている機能はVIMまたは他のコマンドラインエディターと統合できますが、おそらくかなり大きな問題があるでしょう。

• ほとんどのIDEはコード/コメントの折りたたみをサポートし、最終結果は次のようになります。

  通常の代わりに：

  

コメントが不要な場合に備えて、コードを読みやすくします。

ソースコードとドキュメントの作成方法。

http://jasmine.github.io/2.3/introduction.html