你如何记录你的Less？

Question

我使用JSDoc来记录所有我写的JS，但我很好奇人们如何记录他们的少。我想我可以使用JSDoc，但它看起来不正确，因为更少不是JS。如果有一种标准的方式可能允许不同的IDE提供工具支持，我还想避免使用JSDoc记录我的内容。

有没有人知道一个标准的记录方式较少？

Answer 1

记录源代码涉及不同的问题，并且可能有不同的目标，比记录CSS，无论是更少还是其他任何变体。

源代码涉及合同的类和方法，例如参数和返回值的类型和含义。它也可能有复杂的逻辑需要解释，或处理多个条件，或处理各种边缘情况。它可能正在实现一个第三方将使用的API，它应该有自己的可以“读取”的独立文档。像JSDoc这样的系统在设计时考虑到了这一切。阅读代码的人可以很容易地理解各种例程的目的和签名以及逻辑，和注释可以被处理成API文档。

以类似的方式，源代码通常按逻辑组织成模块和类的层次结构。在阅读文档时，通常要从子类的描述跳转到其超类的描述，或直到模块级。像JSDoc这样的工具通过大多数情况下通过吐出一组相互关联的HTML页面也使得这一点变得简单。

另一方面，考虑一个像Underscore这样的库，只有上面的一些部分适用。没有模块，类或类层次结构。相反，它是一包工具。因此，真的不需要很多类似JSDoc的机器。相反，我想要做的是能够读取代码并轻松查看正在发生的事情，或者获得关于提供的功能的叙述，可能有一些代码示例。这就是为什么他们使用Docco，正如评论者所建议的那样。这是完美的。正如评论者所提到的，它可以用于几乎所有的编程语言，包括CSS。与JavaScript等“语言”相比，CSS（通常）比较平坦，并且没有参数和返回值“合同”的概念，也没有复杂的计算，尽管在像LESS这样的系统中，插入和计算。使用CSS，你也有这样的情况：在许多情况下，CSS的效果是可视化的，比如说按钮以特定大小的文本以某种方式着色。我们在CSS中有两个潜在的注释消费者：实际上正在查看CSS代码的程序员，以及想要了解定义的样式以及检查其工作方式的UI设计者或实现者。

就我个人而言，我会在这里采用两种方法，映射到两种类型的消费者。在CSS代码本身，我只是简单地评论一下，描述规则的目的和结构。与此同时，我会建立一个单独的“styleguide”网站，其中包含所有样式的可视化示例。已经有各种尝试来自动创建这样的风格指南，并取得了不同程度的成功。我没有用过它们，所以不能说它们可能有多有用。就我个人而言，我会用手卷的风格指南去。

还值得指出的是，唯一比没有文档更糟糕的是文档错误。无论您采用何种文档方法，您都必须确保它的可持续性和可维护性。从这个意义上来说，简单就好。

最后，让我指出，大量文档的需求与一组样式和类的设计成反比。在巴洛克式的设计中，没有太多意义，因为分类不当，怪异的依赖和糟糕的命名，以及大量的文档。相反，您可能需要关注重构您的CSS，因此它至少有更多的自我记录。