Question

我一直想知道为什么我必须在文本编辑器中编写富文本代码注释，即伪代码（来吧，粗体，下划线！）并返回IDE（集成？）编写实际程序，更不用说确保这些文档保持在代码附近。

所以问题是，如果IDE允许使用富文本代码注释会怎样。它会对任何人有帮助吗？考虑到你可以强调或强调重点并使用标题和子标题，可能会让阴暗的画面变得清晰明白？

（是的，我知道我们可以用*重点*和****** HEADER ******来管理但是让我们开箱即用！

我在谈论集成在IDE中的RTF代码编辑器。

Answer 1

这是一个有趣的问题，因为除了它现在实际上是一个好主意之外，它还推动了我们工作方式的界限。

不混合富文本和代码的所有原因都没有解决这是否会对任何人有所帮助的问题 - 是否还有一个补偿缺点的上行方面。如果没有人提出这样的问题并发明网络，也许我们仍然会使用gopher。

对于源代码注释，一些富文本功能比其他功能更有用：

超链接肯定会有用，因为代码文档经常需要引用代码之外的文档，以及代码中其他地方的文档链接以避免重复
图片会很有用，因为很多情况下最合理的代码文档是图表 - 有些人确实使用UML，例如
列表会很有用 - 例如，此列表在其富文本版本（即HTML）中比Markdown源
字体格式不那么重要 - 粗体和斜体偶尔对强调有用，如果代码片段（例如variableName）在格式不同时更容易阅读，则文字更具可读性;不同的颜色没什么意义
标题通常不会有用，因为如果代码注释太长以至于需要标题来引入结构，那么它应该在代码之外。

具有讽刺意味的是，当您在Stack Overflow上发布富文本注释时，很难反驳代码中的富文本注释 - 您必须诉诸于富文本“有时”的论点。

即使在这里的简短评论中，富文本结果也很有用，当您没有看到格式化版本时，Markdown源仍然是明智的。因此，对于IDE来说，将Markdown注释块渲染为富文本可能是一个很好的折衷方案，并且只要光标位置在注释块中就显示Markdown源。

Answer 2

通常，评论代码的想法是解释您的个人例程（或组件部分）要实现的操作。您不应该使用额外的格式标记这些评论以及其他人可能认为混乱的内容。

如果特定部分需要图像，重点或以其他方式需要更深入的解释，那么就表明需要发行说明或支持文档。我知道，开发人员的克星，但最好保持整洁，轻松支持。

Answer 3

Steve McConell引用复杂格式化评论的问题是，由于他们需要做更多工作才能改变，因此他们更有可能过时。

如果整个团队采用了富文本编辑IDE，那么人们可能能够解决这个问题。但是你会开始采用一种勇敢的，新的代码创建方法，这是大多数团队明智地倾向于避免采用当前最佳实践的方法。

实际嵌入式文档是另一个问题，我不确定处理此问题的最佳方法。

Answer 4

实际上，真正有助于评论代码的是当语言采用最常用的评论模式并将其转换为语言功能时：

final关键字可以取消此类评论：

// Don't extend this class! Ever!

抽象方法取代了这个：

// make sure you implement foo() bar() and baz() in all child classes

良好的面向对象编程将组织代码，这样您就不需要烦人的标题：

// *******************************************
// ***** Input Handling here *****************
// *******************************************
// * This next section has all the functions *
// * dealing with keyboard input.            *
// *******************************************

......变成......

class InputHandler {
    // This class deals with keyboard input.
}

Answer 5

不，因为在没有添加特殊IDE的情况下查看代码的用户可能无法阅读评论。

但是，我可以理解IDE的可自定义的自动格式化。例如，您的IDE可以配置为在Markdown（StackOverflow使用）下处理注释，这样可以获得可读的“代码”。

Answer 6

过去十年，Javadoc已经允许HTML标记和一堆自定义标记（例如链接到其他类或方法）。

Answer 7

我想要的文档结构与源代码的结构不匹配。

例如，功能规范是一个功能列表：每个功能都在一个地方描述......但是功能的实现，例如作为从UI到数据库通过DAL的事务，不是在源代码中的一个位置。

此外，不同的人想要不同类型的文档：

什么是功能规格？
用户界面是什么？
什么是数据设计？
什么是软件设计？
开发项目/流程是什么？
测试用例是什么？
测试结果是什么？

在与源代码相同的源文件中编写文档没有帮助，imo。

但是，另见“文学编程”。我不知道“文字编程”是什么或者原本应该是什么，但它至少在一个狭窄的案例中看起来很有用，也就是说，当你试图写软件时（例如写一篇关于某些软件的文章）

Answer 8

绝对不是！我根本不相信任何人在我的代码中乱用“特殊字符”，有一天，这可能会给我带来另一个令人头疼的问题。

更新：Jeremy指出，在将文件提交给编译器之前，评论（包括任何格式化）总是会被删除。这很好，但我仍然不喜欢在我的代码中加入控制字符的想法。

的一种方法是ReSharper所做的工作。当它“观察”您的代码时，它会以任何以“注意：”开头的注释加粗并变为蓝色。这很有用，因为没有人弄乱我的文本格式 - 他们只是使用基于内容的颜色编码。

再次：不更改我的文件格式。但是根据内容突出显示内容很好。

Answer 9

如果你让这个想法通过并变得流行，有一天你会发现嵌入在某人代码中的Excel电子表格或视频。不，请让源代码，至少是源代码！，是简单的旧文本。

Answer 10

我在评论中真正需要的唯一富文本是引用其他代码段的超链接。使用Javadoc样式的注释或仅使用ctags很容易实现。

如果纯文本注释不清楚，您可能需要更好的文档，而不是更好的文档格式。

Answer 11

我有点喜欢这个主意。由于注释已经是一种颜色，它可能需要有些限制，而不是真正的富文本，否则很难从代码中挑选出注释。但是如果它只允许粗体，下划线和字体大小，那么强调你知道代码是一个kludge，或者“不要编辑这个”类型的注释会很有用。

然而，只有它是普通且广泛使用的IDE的一部分才会起作用。

Answer 12

看一下Visual Studio 2010，它有一个示例扩展，可以将图像插入到代码文件中。

Answer 13

您可以检查使用的phpdoc格式 - 基本上它使用标记来标记内容，但可以包含链接等。

Answer 14

我更喜欢只有javadoc丰富的元素，比如链接到类，标题等以丰富的方式呈现。这将透明地转换为javadoc html。我认为这是一个好主意。

Answer 15

已经可以在Python代码中添加富文本：sphinx。至少以RST的形式。而且它也没有必要使用IDE（虽然我认为一些格式化帮助很有用）。

Answer 16

在NeXT维护他们自己的GCC私有分支的日子里，它允许源代码中的RTF标签。不只是在评论中，而是在所有地方。它从来都不是一个高度利用的功能，并最终被淘汰。一个问题是RTF真的很难用纯文本编辑器阅读，所以只有团队中的每个人都使用了一个RTF感知编辑器（和diff工具）才能使用它。

我认为在评论中保留某种格式可能会有用，但我认为比RTF更具人性化的东西可能是一个更好的主意。 Markdown可能效果很好。

富文本会帮助评论代码吗？

16 个答案: