ドキュメントよりも例を優先してください。それは行動上の問題ですか？

23

新しいAPIやプログラミング言語、または単純なLinuxのマニュアルページに出会うたびに、私は常に（覚えている限り）それらを避け、代わりに新しい概念の理解を得るために例に頼りました。

無意識のうちに、私はドキュメンテーション/ APIを、それが単純明快で、不可解であるか、または単なる退屈でないときは避けます。プログラミングを始めてから何年も経ちましたが、今では公式の例よりも百万倍優れているので、不可解な/難しい文書を読むことを控えることでより多くの損害を引き起こしていることに気づき、自分の道を修復する必要があると感じていますドキュメントには、他の例よりも多くの記事があります。例が学習のための「主要な」ソースの代わりに「追加された」値として扱われるべきであることに気付いた後でさえ。

プログラマとしてこの悪い習慣を打破するにはどうすればいいのでしょうか？

programming-practices api

— user6123723
ソース

3

私はそれが悪い習慣だとは思わない。私は常に例から始め、必要に応じてドキュメントを読みます。

— カプタン

1

a million times better than examples as the official documentation has more coverageいつも、私は例を挙げて、過去にいくつかの素晴らしい文書化されていない機能を見つけたない-

— Izkata

ドキュメントは、概念を例で伝える必要があります。私は通常、文書化の失敗としてではないドキュメントを検討します。

— svidgen

30

例に優先的に依存する習慣は何も悪いことではありません。あなたにとって、それはあなたの答えを得る最も速い方法です。さらに、例は視覚的です。テキストの段落を読んで必要な情報を抽出するよりも、例を視覚的に解析する方が簡単です。

例：

製品を一覧表示するには、ここで唯一可能な動詞IndexであるProductsコントローラーGETのアクションを使用する必要があります（データベースからの製品の作成、変更、削除に使用されるアクションの詳細については、[製品への影響]を参照してください）。

特定の製品に関する詳細情報を取得するには、URIの末尾に一意の識別子を追加します。利用可能なすべての製品のリストを取得する場合は、何も追加しないでください。マニュアルの[データを選択するためのレストフィルタ]セクションで説明されているように、フィルタを使用することもできます。製品のリストは1,000アイテムに制限されていることに注意してください。[ページネーション]を使用すると、各ページがまだ1,000アイテムに制限されているため、リスト全体を確認できます。

サービスに在庫の数量を更新させることもできます。これは、refresh-quantitiesを1に設定することにより行われます。

詳細ですが、退屈でほとんど読めません。リンクをたどる必要があるという事実は、事態をさらに悪化させます。サンプルを追加すると、理解しやすくなります。

GET Products / Index /
GET Products / Index / 12345 /
GET Products / Index /？skip = 100＆take = 20
GET Products / Index /？category = 12
GET Products / Index /？price = 0..39.90
GET Products / Index /？ category = 12＆skip = 100＆take = 20

サンプルのみを使用するという事実が問題になる場合があります。例の使用を単純に停止しないでください。ただし、アイデアが得られたら、より詳細なドキュメントが役立つことを忘れないでください。たとえば、上記のサンプルでは、製品のリストが1 000に制限されていることは示されていません。そのためのドキュメントを読む必要があります。

ドキュメントを読む必要があることをいつ知っていますか？

APIまたはライブラリが期待どおりに動作しないたびに。たとえば、サンプルを取得して実行します。

GET Products / Index /？skip = 6000＆take = 3000

何らかの理由で、データベースに2万以上の製品があるのに、返されるアイテムは3 000未満です。ここでは、のようなAPIが動作していない、あなたが期待されるので、詳細なドキュメントを読むには良い時間です。

— アルセニ・ムルゼンコ
ソース

完全に理にかなっています。例によって道が開かれたとしても、常にドキュメントに戻ってください！

— user6123723

2

さらに、時にはあなたがおそらく決して見つけることのないドキュメントを徹底的に読むことによって、物事を行うための本当にシンプルでエレガントで簡単な方法を見つけることがあります。解決するユースケースはありません）。

— エイミーブランケンシップ

10

ドキュメントによって提供される情報は、次の3つのカテゴリに分類されます。

レシピ。
参照。
専門知識。

レシピや例は、問題のあるドメインとソフトウェアの機能の間の橋渡しをします。リファレンスにはいくつかの機能が完全に説明されており、レシピを特定のケースに適合させたい場合に役立ちます。

（専門知識は、問題領域の概念を文書化の概念にマップします。概念をいくつかの方法で表現できる場合、またはソフトウェアのユーザーがこの分野の専門家でない場合に役立ちます。）

プログラマーとしてのこの悪い習慣をどのように破りますか、または私は考えすぎていますか？仲間のプログラマーからの知恵は大歓迎です。

あなたの習慣が悪いとは思いません。APIを学習すると、最初にどの問題を解決できるか、どの方法論がRecipes（例）の助けを借りて提供されるかがわかります。リファレンスドキュメントは、特別なケースに合わせて方法論を微調整するのに役立ちます。

— マイケルルバルビエグリュネヴァルド
ソース

3

恐竜の時代、すべてのプログラムが専門的に書かれたドキュメントを印刷していた頃、通常、リファレンスマニュアルとユーザーガイドの2冊の本がありました。リファレンスマニュアルは、すべてが何をするのかを明確に示した仕様であり、ユーザーガイドはユースケースの集合でした。両方とも重要かつ有用でした。

— ロスパターソン

2

例はドキュメントです。APIの観点に精通することから悪いことではないと思います。それがあなたが見ている唯一のドキュメントである場合、それは問題になる可能性があります。ほとんどの例では、エラーチェックを省略しているため、戻って参照ドキュメントから欠落している部分を取り戻さないと、コードが過度に脆弱になる可能性があります。

— ストーンメタル
ソース

驚くばかり。私の主な関心事は、例から得られた知識のみを使用することであり、ドキュメントにはさらに多くの価値があるため、それを読み損ねると、それを使用できません。問題を理解したので、これをもっと真剣に考えるべきです。

— user6123723

1

さまざまな人々がさまざまな方法でより良く学びます。一部の人々はあなたに似ていて、例からよりよく学びます。一部の人々は私のようであり、詳細なドキュメントからよりよく学びます。ドキュメントに両方があると、ほとんどの開発者をかなりうまくカバーしているようです。教師と話をすると、彼らは人々が学ぶ方法を6つ以上教えてくれます。

— ポール・シャーフ
ソース