比文档更喜欢示例。这是行为问题吗？

每当我遇到新的API或编程语言，甚至是简单的Linux 手册页时，我总是（从我记得以来）就避免使用它们，而是懒惰地依靠示例来理解新概念。

在潜意识中，无论文档/ API不是简单明了，晦涩难懂还是无聊，我都会避免使用它。自从我开始编程已经有好几年了，现在我觉得我需要修正自己的方式，因为我现在意识到我要避免阅读晦涩难懂的文档，从而造成更大的损失，因为它仍然比官方示例高一百万倍文档的覆盖面比那里的任何示例都多。即使意识到这一点，示例也应被视为“附加”价值，而不是“主要”学习资源。

我该如何改掉作为程序员的这种坏习惯？

优先依赖示例的习惯没有错：对您而言，这只是获得答案的最快方法。而且，例子是视觉的。从视觉上解析示例比阅读文本段落并提取所需信息要容易得多。

例：

为了列出产品，应该使用控制器的Index动作Products，因为这GET是此处唯一可能的动词（有关用于从数据库创建，修改和删除产品的动作的更多信息，请参见[影响产品]）。

为了获得有关特定产品的详细信息，请将其唯一标识符附加到URI的末尾。如果要获取所有可用产品的列表，请不要添加任何内容。您也可以使用过滤器，如手册的[用于选择数据的REST过滤器]部分中所述。请注意，产品列表限制为一千个项目。[分页]可用于遍历整个列表，因为每个页面仍限于一千个项目。

您可能还需要强制服务刷新库存数量。这是通过将设置refresh-quantities为1 来完成的。

详细，但无聊且几乎不可读。您需要点击链接的事实使事情变得更糟。如果我们附加一些示例，将变得更容易理解：

GET产品/索引/
GET产品/索引/ 12345 /
GET产品/索引/？skip = 100＆take = 20
GET产品/索引/？category = 12
GET产品/索引/？价格= 0..39.90
GET产品/索引/？ category = 12＆skip = 100＆take = 20

仅使用示例的事实可能是一个问题。不要简单地停止使用这些示例，但是请记住，一旦您有了主意，则更详细的文档可能会有所帮助。例如，上面的示例并未显示产品列表限制为1 000：您必须阅读该文档。

您什么时候知道应该阅读文档？

每次API或库的行为均不符合您的预期。例如，您获取示例并执行以下操作：

GET产品/索引/？skip = 6000＆take = 3000

由于某种原因，它返回的商品少于3000个，而数据库中却有超过2万种商品。在这里，该API的行为不像您预期的那样，因此是阅读详细文档的好时机。

文档提供的信息分为三类：

• 食谱。
• 参考。
• 专业知识。

配方或示例在问题域和软件功能之间架起了桥梁。参考完全描述了某些功能，如果您想使配方适应特定情况，则参考非常有用。

（专家知识将问题域的概念映射到文档的概念，如果可以以多种方式表达概念，或者如果软件的用户不是该领域的专家，则很有用。）

我该如何改掉作为程序员的这种坏习惯？感谢其他程序员的智慧。

我不认为你的习惯不好。在学习API时，您首先会了解可以解决哪些问题以及在食谱的帮助下提供了哪些方法（您的示例）。然后，参考文档可帮助您将方法论调整为特殊情况。

示例是文档。从熟悉API的角度来看，我认为这并不坏。如果这是您查看的唯一文档，则可能是一个问题。如果您不回过头来从参考文档中获取缺失的部分，大多数示例会跳过错误检查，这可能会导致代码过于脆弱。

不同的人以不同的方式学习得更好。有些人喜欢你，可以从例子中学到更多。有些人像我一样，可以从详细的文档中学到更多。两者都包含在文档中似乎可以很好地覆盖大多数开发人员。与老师交谈，他们可以告诉您六种学习方法。