コメントでの新しい構文または一般的でない構文の説明
タイトルどおり、将来コードを検討している開発者がそれに慣れていないことが合理的に予想される場合、コードで使用する構文を説明する必要がありますか？短い警告または説明をインラインで追加できますが、より複雑な構造は名前とバージョン番号で参照され、ドキュメントをすばやく検索できます。
彼らが構文を理解できないかもしれない2つの主な理由は、それが言語への新しい追加であるか、または「平均的な」開発者がめったに使用しない構文だからです。この構文の使用が推奨されるアプローチであり、私が豪華なコードを書きたいと思っているわけではないと仮定します。 （いいえ、私は XORスワッピング 高級言語ではありません。）
一方で、コメントはメンテナンスを容易にするためにあり、その説明を提供すると、将来の開発者の多大な労力と読書を節約できます。一方、構文のドキュメントはすぐに入手でき、適切な開発者は新しい開発について最新の状態を保つことが期待でき、そうでなければ、ツールを使用してそれを理解するのに問題はないはずです（IDEヘルプ）と彼が利用できるドキュメント。
コンテキストについては、SAPの [〜＃〜] abap [〜＃〜] 構文に新しい grouping および filtering を追加する構文の最近の更新によってこの質問が促されました=ループのメカニズムといくつかの その他のステートメント 。多くのレガシー開発者やクライアント側のメンテナンスチームは、この構文に何年も慣れていません（あるとしても）。
この質問の場合 コードにコメントを付けることをお勧めします 。
Cswがコメントしているように、1つのオプションは、メンテナが追いつくまでこの新しい構文を使用しないことです。私の業界では、プロジェクトが提供されると、コードのメンテナンスが小規模な社内開発者に引き渡されることが多く、「レガシーモード」でスタックすることで悪名高くなります。時代遅れのプログラマーのために、機能的に時代遅れのコードを松葉杖として書くことは、良いまたは防御可能な習慣のようには思えません。
私の特定の状況では、ABAP構文の更新により、パフォーマンスと可読性が劇的に向上します。それらは、キャスト演算子のような古代のABAP言語に多くの一般的な現代の操作を導入します。 GROUP BYリンクしたのは、複雑で判読不能でバグが発生しやすいコードを単純な代替手段に置き換えるもう1つの良い例です。具体的な構文例については、私は置き換えることができます
READ TABLE itab WITH ... TRANSPORTING NO FIELDS.
IF sy-subrc = 0.
...
ENDIF.
と：
IF line_exists( itab[ ... ] ).
...
ENDIF.
興味のある方のために、 このPDF は多くの新機能をカバーしています。スライド29と30は、違いがどれほど劇的であるかを示す2つの良い例です。
推奨される重複 に関して、いくつかの役立つ回答がありますが、私の質問はより具体的なケースをカバーしています。私の質問を「私はdocument *why* rather than *how*パラダイムを使用すると、経験の浅い開発者のメンテナンスが大幅に簡略化される場合があります。 ".
ABAPのコンテキストでは、次の理由により、誰もがすべての最新機能に精通しているとは限りません。
- ABAPには非常に長い歴史があり、古代言語の構成要素が常に出会います（現在、論理データベースを使用し、ヘッダー行を含むテーブルを過度に使用するレポートを変更しています）。
- SAP自体が新機能を使用して、まだ新しいリリースにパッチが適用されていないシステムとの下位互換性を確保することはほとんどないため、新機能が「実際に」使用されることはほとんどありません。
- SAPの教育コースは非常に費用がかかるため、企業は必要のない人に人を送ることを避けています必死に仕事に必要です。新機能を説明するデルタコースは、十分に重要であるとはめったにありません。
組織が最新の開発手法に対応していない場合、異常な構文の説明が不要になるように、最新の状態にすることを使命とすることを検討してください。これがオプションではない場合（時間がない、リソースがない、そしてこれが自分の責任であると感じていない）場合は、他のチームメンバーを混乱させないように新機能を回避するか、コメントしてください。
良いコメントのルールを覚えておいてください：
- 初心者は構文を説明します
- 見習いは何が起こっているのかを説明します
- 専門家はそれが起こっている理由を説明します
悪い：
" This uses the new line_exist operator in 740 which replaces READ TABLE
IF line_exists( itab[ carrid = 'AE' ] ).
PERFORM foobar.
ENDIF.
そのオペレーターを知っているとき、このコメントは私にはまったく役に立ちません。また、2028年である可能性があり、そのオペレーターが何年も前に廃止されたと宣言されたため、「新しい」と言って笑ってしまうかもしれません。オペレーターがわからないときは、コードを理解するのを助けるのではなく、10分間のグーグルプレイを送ってくださいました。
より良い：
" When any position has the carrier 'AE', we need to do the foobar operation
IF line_exists( itab[ carrid = 'AE' ] ).
PERFORM foobar.
ENDIF.
これは何が起こっているのかを教えてくれるので、この新しい言語機能が何をしているかを理解する必要すらありません。知らなかったとき、あなたはそれが何をするかを私に示しただけだったので、あなたから何かを学びました。そして、私がすでにそれを知っている場合でも、あなたのコメントはあなたのコードよりも読みやすく、プログラムを理解するのに役立ちます。
さらに良い：
" Anytime there is at least one flight by carrier AE on the
" flight list, the foobar operation must be performed to prevent
" all the foobaz from getting confabulated.
IF line_exists( itab[ carrid = 'AE' ] ).
PERFORM foobar.
ENDIF.
何が起こっているのかだけでなく、それがどのような目的を果たしているのかも教えてくれます。
他の答えに反して、私はノーと言うでしょう。コードはできるだけ自己文書化する必要があります。そのような単純なことはコードで説明する必要はありません。
私はSAPを知りませんが、 SAPリファレンスページ を指す単純なgoogleクエリがline_exists 関数。
メンテナと開発者が最新でない場合、会社はそれらを最新に保つための戦略を開発する必要があります。
状況によると思います。
この例では、このようなドキュメントはREADMEファイルに含まれています。* 新しい構文を一貫して使用すると、コードは、古いスタイルしか知らないプログラマには事実上認識されなくなります。メンテナは、実際にはこの言語を知らないことを事前に警告すると、感謝します。私は...するだろう：
このファイルが新しい構文を使用することを太字のブロックコメントですべてのソースファイルを開始します。
*********************************************** * ### This file uses the NEW ABAP SYNTAX ### * * ### introduced in NetWeaver 7.4. ### * * ### Please see README.html for details. ### * ***********************************************READMEで、構文の変更を簡単に説明し、チュートリアルと参照へのリンク（したがってREADME。html）を提供します。
これには2つの利点があります。
READMEは複数のプロジェクトで再利用できます。繰り返してはいけません！
コードはコメントの半分にはなりません。新しい構文が各ファイル全体に存在するようです。構文を簡単に説明すると、どこで使用するにしても、面倒で、メンテナが読むのが難しくなります。
* 警告：あなたの投稿のリンクから学んだABAPについて知っているすべてのこと。これは専門家の意見ではありません。
** ちなみに、上記のサンプルブロックコメントは、ここにライセンスされています CC0 1. :)。都合がよければ、自由にコピーしてください。
この場合、更新に慣れていない人は単にline_existsと一緒に移動します。
検索しにくいものについては、使用している新機能に単に名前を付けるコメントを残して、最新のドキュメントを見つけやすくすることができます。これらの機能を数か所以上で使用する場合は、そのような通知をコメントではなくreadmeファイルに入れてください。
別のソースからの十分なドキュメントがすでにある場合、私は構文を説明する気になりません。代わりにyo開発するものをドキュメント化する労力を節約してください。
注：私はABAPにあまり詳しくないので、Javaでラムダを使用することについて誰かが質問したかのように、問題が類似している（AFAIKである）と理解して回答しています。間違いの場合はお知らせください。
これはプロジェクトの仕様の問題であるため、コメント（コードの一部）には属しません。実際、新機能の使用を決定するのはプログラマーではなく、プロジェクトと互換性のあるABAPのバージョンを決定するのはプロジェクトマネージャーまたは製品所有者ですらあります。
プロジェクトのドキュメントのどこかに、「Supports ABAP X」のようなものを書く必要があります。今：
Xが1990の場合、ABAP 1990と互換性のない機能は使用しないでください。これらの新機能が非常に付加価値を高め、Xを2015に変更することが望ましいと思われる場合は、その責任者に相談してください。彼らがプロジェクトの仕様を更新するかどうかの決定。
Xが2015の場合、新しいプログラマーは、コードを読み取るためだけに新機能についてある程度の知識が必要であることを知っています。そのようなバージョンの言語を学習（または形成を要求）するのは、彼らはまだそれに慣れていません。
ある面では、これは少しX-Yの問題だと思います。
私の例のために、私はこれを読んでC++の最近のC++ 11の見直しを検討してほしいと思います。特にconstexprに焦点を当てたいと思います。その目的は、コンパイル時に特定の関数（階乗関数など）をコンパイラーで実行できるようにすることです。これにより、実行時に定数値を計算する必要がなくなります。
私がC++ 11機能のいずれも読んだことがないC++開発者でいっぱいの開発チームにいることを主張するために言います（このシナリオをもう少し現実的にするために2012年にいるとします）。私はint factorial(int n)関数を取り、constexprを追加します。これを文書化する必要があります。 constexprを追加した理由を説明するコメントを書いたり、プロジェクトの変更ログに本当にそのようなものがあるのですか？
コメントはコードの現在の状態を説明するためのものであり、コードが行った変更を説明するためのものではないと私は主張します。削除したすべてのバグにコメントを残すのではなく、変更ログまたはエラーログにメモします。同様に、factorialをconstexprにする理由は、変更ログに記載する必要があります。
ただし、関数の動作を変更したため、コメントは変更する必要があります。実行時には動作せず、コンパイル時に実行されます。したがって、コメントを//Calculates the result of the factorial operationから//Calculates the result of the factorial operation at compile timeに変更します。
「ああ、その機能を説明したところだ」と思われる方もいらっしゃると思います。いいえ。私がやったことは、コメントに関数の動作を説明させることです。私がしなかったことは、constexprの使用に関連するすべての警告を説明することです（つまり、constexprを関数に適用するとコンパイルエラーが発生する状況については説明していません）。
より読みやすい形式を使用するようにいくつかの構文を変更した場合、コード自体の動作を変更しなかったため、コメントにそのような変更を文書化しませんでした。代わりに、変更を変更ログに記録します。
いくつかの特定のポイントに対応して：
この構文が推奨されるアプローチであると想定します
推奨されるアプローチの場合は、それを使用する必要があります。これを使用しない唯一の理由は、それが何かを壊したり、使用するツール（C++ 11の一部の機能など）でまだ広くサポートされていない場合です。
一方で、コメントはメンテナンスを容易にするためにあり、その説明を提供すると、将来の開発者の多大な労力と読書を節約できます。
そして、言語機能の完全な内外を学ぶことから彼らを奪いますか？あなたは誰かにスパナを与えて、それが調整可能であるという事実を省きません。他のコーダーの1人が構文機能のすべての警告の代わりに要約を読んだために重要な事実を見逃した場合、それが原因でバグが発生した場合、それは事実上あなたの責任です。確かにドキュメントを読まなかったのは彼らのせいでしょうが、なぜ彼らはそれを読まなかったのですか？コメントを通じて機能について学んだからです。
プロジェクトが配信されると、「レガシーモード」で立ち往生することで悪名高くなります。
そして、彼らにドキュメントを読むことを強いることによって、あなたはこの習慣から彼らを強制しているのです。これはgoodthing™です。 PDFをダウンロードする価値があるのは、新しい構文が現代の考え方にはるかに一致していることです。繰り返しますが、これはgoodthing™であり、コードの可読性、パフォーマンス、または保守性を向上させる新機能の採用を奨励する必要があります。ドキュメントを読むのに費やされた時間は、読者が何かを学べば無駄にはなりません。