ide - リッチテキストはコードのコメントに役立ちますか?

Question

テキストエディタでリッチテキストコードコメント別名疑似コードを記述し（太字、下線を付けてください！）、IDE（統合？）に戻って実際のプログラムを作成する必要があるのはなぜだろうかといつも思っていました。これらのドキュメントはコードの近くにとどまります。

問題は、もし IDE がリッチテキストコードコメントを許可したらどうなるかということです。それは誰かを助けるでしょうか？重要なポイントを強調または強調し、ヘッダーとサブヘッダーを使用できることを考慮して、あいまいな画像をより明確に理解できるようにすることはできますか?

(ええ、*重要な点* と ****** HEADER ****** で対処できることはわかっていますが、すぐに使える状態で少し考えてみましょう!

私が話しているのは、IDE 内に統合された RTF コードエディターです。

score 12 · Accepted Answer

これは興味深い質問です。なぜなら、それが現在実際に良いアイデアであるかどうかは別として、私たちの働き方の境界を押し広げているからです。

リッチテキストとコードを混在させない理由はどれも、これが誰かの役に立つかどうか、つまりデメリットを補うメリットがあるかどうかという問題には対処していません。誰もこの種の質問をせず、Web を発明しなければ、おそらく私たちはまだ gopher を使用していたでしょう。

ソースコードのコメントに関しては、一部のリッチテキスト機能が他の機能よりも便利です。

コードのドキュメントは、重複を避けるために、コードの外部にあるドキュメントや、コード内の他の場所にあるドキュメントへのリンクを頻繁に参照する必要があるため、ハイパーリンクは確かに便利です。
最も賢明なコードドキュメントが図である場合が多いため、画像が役立ちます。たとえば、UML を使用する人もいます。
リストが便利です。たとえば、このリストは、Markdown ソースよりもリッチテキストバージョン (つまり、HTML) の方が読みやすいです。
font-formattingはあまり重要ではありません - 太字とイタリック体は強調するのに役立つ場合があり、コードの断片 (avariableNameなど) が異なるフォーマットで読みやすい場合は、テキストが読みやすくなります。色の違いはほとんど意味がない
コードコメントが長すぎて構造を導入するために見出しが必要な場合は、おそらくコードの外にある必要があるため、見出しは通常は役に立ちません。

皮肉なことに、スタックオーバーフローにリッチテキストコメントを投稿する場合、コード内のリッチテキストコメントに反対するのは難しくなります。

ここでの短いコメントでも、リッチテキストは有用であることがわかります。また、書式設定されたバージョンが表示されない場合でも、Markdown ソースは適切なままです。そのため、IDE が Markdown コメントブロックをリッチテキストとしてレンダリングし、カーソル位置がコメントブロック内にあるとすぐに Markdown ソースを表示することが、おそらく適切な妥協案となるでしょう。

score 5 · Accepted Answer

一般に、コードにコメントを付けるという考え方は、個々のルーチン（またはコンポーネントパーツ）が実行することを目的としたアクションを説明することです。これらのコメントを余分なフォーマットでマークアップする必要はなく、他の人が雑然と考えるかもしれません。

特定のセクションに画像が必要な場合、強調する必要がある場合、またはその他の方法でより深い説明が必要な場合は、リリースノートまたはサポートドキュメントの必要性を示しています。開発者の宿敵は知っていますが、物事を整頓し、簡単にサポートできるようにしておくことをお勧めします。

score 4 · Accepted Answer

複雑な形式のコメントについてSteveMcConellが引用している問題は、変更する作業が多いため、古くなる可能性が高いことです。

チーム全体がリッチテキスト編集IDEを採用すれば、この問題を回避できる可能性があります。しかし、あなたは勇敢で新しいコード作成方法論に着手するでしょう。これは、ほとんどのチームが現在のベストプラクティスを採用することを支持して賢明に避けがちなことです。

実際の埋め込みドキュメントは別の質問であり、これに対処する最善の方法がわかりません。

score 4 · Accepted Answer

実際、コードにコメントを付けることが本当に役立つのは、言語が最も頻繁に使用されるコメントパターンを取り、それらを言語機能に変換する場合です。

キーワードは、このfinalタイプのコメントをなくすことができます:

// Don't extend this class! Ever!

抽象メソッドはこれを置き換えます:

// make sure you implement foo() bar() and baz() in all child classes

また、優れたオブジェクト指向プログラミングではコードが整理されるため、煩わしい大きなヘッダーは必要ありません。

// *******************************************
// ***** Input Handling here *****************
// *******************************************
// * This next section has all the functions *
// * dealing with keyboard input.            *
// *******************************************

... になる ...

class InputHandler {
    // This class deals with keyboard input.
}

score 3 · Accepted Answer

いいえ。特別なIDEを追加せずにコードを表示するユーザーは、コメントを読み取れない可能性があるためです。

ただし、IDEのカスタマイズ可能な自動フォーマットについては理解できます。たとえば、IDEをMarkdown（StackOverflowが使用する）の下でコメントを処理するように構成できます。これには、読み取り可能な「コード」があるという利点があります。

score 3 · Accepted Answer

Javadocは、過去10年間、HTMLタグと一連のカスタムタグ（他のクラスやメソッドへのリンクなど）を許可してきました。

score 3 · Accepted Answer

ドキュメントに必要な構造がソースコードの構造と一致していません。

たとえば、機能仕様は機能のリストです。各機能は1つの場所で記述されますが、たとえばUIからDALを介したデータベースへのトランザクションとしての機能の実装は、1つの場所ではありません。ソースコードで。

また、さまざまな人々がさまざまな種類のドキュメントを求めています。

機能仕様は何ですか？
UIとは何ですか？
データデザインとは何ですか？
ソフトウェアの設計は何ですか？
開発プロジェクト/プロセスは何ですか？
テストケースは何ですか？
テスト結果は何ですか？

ドキュメントをソースコードと同じソースファイルに入れても役に立ちません、imo。

ただし、「文芸的プログラミング」も参照してください。「文芸的プログラミング」が何であるか、または何を意味するのかはわかりませんが、少なくとも1つの狭いケース、つまりソフトウェアについて書き込もうとしている場合（たとえば、ソフトウェアに関する記事を書く場合）に役立つように見えます。。

score 2 · Accepted Answer

絶対違う！私は、誰かが私のコードを「特殊文字」でいじくり回しているとは信じていません。これは、いつか私に別の頭痛の種を与える可能性があります。

更新：Jeremyは、ファイルがコンパイラーに送信される前に、コメント（フォーマットを含む）は常に削除されると指摘しています。これは問題ありませんが、コードに制御文字を入れるという考えは今でも内臓的に嫌いです。

うまくいく1つのアプローチは、ReSharperが行うことです。コードを「監視」しているときは、「注：」で始まるコメントは太字で青色に変わります。誰も私のテキスト形式をいじっていないので、これは便利です-彼らはコンテンツに基づいた色分けを使用しているだけです。

繰り返しになりますが、ファイル形式を変更しないでください。ただし、コンテンツに基づいて強調表示することは問題ありません。

score 2 · Accepted Answer

このアイデアを通過させて人気を博すと、ある日、誰かのコードに埋め込まれたExcelスプレッドシートまたはビデオが見つかります。いいえ、お願いします、ソースコード、少なくともソースコード！をプレーンな古いテキストにしてください。

score 1 · Accepted Answer

私がコメントで本当に望んでいる唯一のリッチテキストは、他のコード部分を参照するためのハイパーリンクです。これは、Javadoc スタイルのコメントまたは単に ctags を使用するだけで簡単に実現できます。

プレーンテキストのコメントが明確でない場合は、ドキュメントの形式を改善するのではなく、ドキュメントを改善する必要があります。

score 1 · Accepted Answer

私はそのアイデアが好きです。コメントはすでに 1 色であるため、真のリッチテキストではなく、ある程度制限する必要があるでしょう。そうしないと、コードからコメントを選択するのが難しくなります。ただし、太字、下線、およびおそらくフォントサイズのみを許可する場合は、コードがくだらない、または「これを編集しないでください」タイプのコメントであることを強調するのに役立ちます。

ただし、一般的で広く使用されている IDE の一部になるまでは機能しません。

score 1 · Accepted Answer

Visual Studio 2010 を見てください。コードファイルに画像を挿入する拡張機能の例があります。

score 0 · Accepted Answer

使用されているphpdoc形式を確認できます。基本的にはタグを使用してコンテンツをマークしますが、リンクなどを含めることができます。

score 0 · Accepted Answer

NeXTがGCCの独自のプライベートブランチを維持していた時代には、ソースコードでRTFタグを許可していました。コメントだけでなく、どこでも。これはあまり利用されていない機能であり、最終的には削除されました。1つの問題は、RTFがプレーンテキストエディターでは非常に読みにくいため、チームの全員がRTF対応エディター（およびdiffツール）を使用した場合にのみ機能することでした。

コメントにある種のフォーマットを保持することは潜在的に役立つと思いますが、RTFよりも少し人間が読める形式の方が良いと思います。マークダウンはかなりうまくいくかもしれません。

score 0 · Accepted Answer

リッチテキストを Python コードに含めることは既に可能です: sphinx。少なくとも RST の形式で。また、IDE を使用する必要もありません (ただし、書式設定のヘルプが役立つと思います)。

score 0 · Accepted Answer

、クラスへのリンク、ヘッダーなどの javadoc リッチ要素のみをリッチテキスト形式で表示することをお勧めします。これは透過的に javadoc html に変換されます。アイデアとしては良いアイデアだと思います。

ide - リッチテキストはコードのコメントに役立ちますか?

16 に答える 16

Related

Reference