問題タブ [self-documenting-code]

慣習を学ぶ価値はありますか、それとも可読性と保守性を損なうものですか?

たとえば、Javaでは、@Overrideアノテーションはオーバーライドのコンパイル時チェックを提供するだけでなく、優れた自己文書化コードを作成します。

私はドキュメントを探しています（ただし、それがpylintのようなチェッカーの指標である場合、それはボーナスです）。コメントやdocstringをどこかに追加できますが、Pythonでオーバーライドを示す慣用的な方法は何ですか？

一貫性を保つために、単純なゲッターとセッターのメソッドや非常に小さなラッパークラスであっても、すべてのメソッドとクラスに（JavaDocの形式で）コメントを常に適用しています。しかし、私はまた、コメントを不要にすることが多い自己文書化コードの記述にも努めています。つまり、必要な場所にのみコメントを書き込みます（その前に、コメントがまったく必要ないようにコードを書き直してみてください）。したがって、これら2つのアプローチは互いに矛盾しているように見えます。

では、メソッドまたはクラスを説明するコメントは一貫した方法で適用する必要がありますか、それともそのようなコメントは、定義から意味が完全に明確でない場合にのみ書き込む必要がありますか？

これらの 2 つの概念は直感に反するように見えます。コメントが可読性に悪影響を及ぼし、DRY に違反している (コメントが最新の状態に保たれている場合) という意見もあります。ただし、コインを裏返すと、他のユーザーがライブラリを使用できるように、コードの適切な API ドキュメントを提供する必要があります。

API ドキュメントを生成するために設計されたすべてのツール (JSDoc、PDoc など) は、そのドキュメントを提供するために非常に多くのスペースを使用します。API ドキュメントを提供する必要がありますが、必要ではないのは、LOC の半分を特別にフォーマットされたコメントにして、JSDoc が読み取れるようにすることです。

現在、 Jekyllのような基本的なマークダウン ツールを検討しており、このドキュメントを /doc フォルダーに配置して、コードから完全に削除しています。他の誰かがこの問題へのアプローチを見つけましたか?

厳密に型指定された列挙型の列挙子をフラグとして (組み合わせて) 使用できる小さなクラスを作成しました。基になる型の検出に type_traits を使用しているため、わずかに型安全であり、ほとんどがコンパイル時に処理されるはずです。とはいえ、本当にお得かどうかは疑問でした。

私は今のようなものを書くことができます

プログラマーは、Mode の列挙子 (Mode::Read など) のみを使用でき、他の列挙型を Mode と組み合わせることができないことがわかります。よりも良い方法だと思いますか

、人々がそれを評価できるかどうかはわかりませんか？

私は nodejs + Express で REST API を開発しており、同時に README ファイルで API を文書化しており、それを自動化できるかどうか疑問に思っていました。例えば与えられた：

これを自動生成してほしい

プラグインの作成方法に関するリファレンスを含む、JQL に関するチュートリアルの優れたリストを見つけました [1]。JQL クエリにコメントを追加することはできますか?

たとえば、アイテムを文書化するために、スプリントの「番号」が jira スプリントの「id」と異なることを文書化できるようにしたいと考えています。 sprint = 777 (* Agile sprint #50 *)

//アップデート ; スプリントを開いてすぐにスプリント ID が作成されないようです。新しいスプリントを開始したばかりですが、レポート ページを閲覧したところ、番号がありません...

1.[]; ; ; ; ; X.JQL総集編！1 つの投稿ですべてを参照してください。; http://blogs.atlassian.com/2013/03/jql-recap/

私は Swift から Kotlin に移行していますが、今のところ気に入っています。ただし、私はこのようなメソッドを宣言することに慣れています (参照されたメソッドが存在し、機能するふりをします):

そしてそれらを次のように呼び出します：

これは自己文書化が美しく、英語のように読めます。ただし、Kotlin では、次のような同様の方法があります。

という名前の変数を使用すると、すでに奇妙に聞こえ始めますinRect。しかし、それを呼び出すとさらに悪化します。

ここに最大の問題があります。この行だけを読むmyRectと、円が描かれる四角形であることが推測できます。しかし、何trueですか？はい、アンチエイリアシングの可能性がありますが、不透明に描画するかどうか、またはまったく描画するかどうかについてのトグルも可能です! とにかく、Swift と Objective-C のプログラマーがメソッド呼び出しのラベルを好む理由をもっと挙げることができますが、私の主張はここまでです。

Kotlinのメソッド呼び出しでラベルを有効にする方法はありますか?

Lua 関数のコントラクトを明確にする方法を探しています。特に、パラメータが持つべき属性。

私の問題を説明するために、現在のコードの典型的な構造を持ついくつかのコード スニペットを示します。2 つのパブリック関数で新しい「インスタンス」を構築する関数。

同じシグネチャ (またはスーパーセット) を持つと想定されるパラメーターを受け取る関数。

後の関数の呼び出し

このコードの問題は、 の実装を見ないと、 にtextPrinter提供されたパラメータがどのように見えるべきかを判断できないことです。この例では簡単に実行できますが、多くの場合、そうではありません (私のシナリオでは、ファイル間のホッピングを強制します)。名前の類似性を除けば、を介して適切な値を取得できるというヒントもありません。printSomeStuffprintSomeStuffnewTextPrinter

コードをより自己文書化し、作成者の意図をより明確にする方法はありますか?

私は軽量で、クラスベースの継承をエミュレートしようとしないアプローチを好みます。同様に、ドキュメンテーションよりもコードが好まれ、そうでない場合は、フリー フォームよりもツールが理解できる形式のドキュメンテーションが好まれます。textPrinter明らかに、「パラメーターのニーズprintとパブリック関数」のようなコメントを書くことができますprintBigが、ドキュメントで犯した間違いについて何も教えてくれなかったり、コードをリファクタリングして更新するのを忘れたりすると、非常にエラーが発生しやすくなります。

私はLua 5.0を使用していますが、この言語にはまったく慣れていません。

ファイル処理を実装するオブジェクトの内部にいるとします。読みやすいようにコードを書きたいと思います。

特に複数のネストされた関数呼び出しがある場合に、戻り値の型を伝えるのが難しいコードの例:

この例は、明確化変数を導入することで読みやすくなっています。

理論的には、コンパイラは一時的に doCreateAction() からの結果を保存する必要があるため、2 番目のバージョンは同じように動作する可能性があります (おそらく、hiddenm、匿名、短命の一時変数内)。名前付き変数に代入するとき、このコードは遅くなりますか?