10

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

所以问题是，如果 IDE 允许富文本代码注释会怎样。它会帮助任何人吗？考虑到您可以强调或强调重点并使用标题和子标题，也许会使模糊的图片更清晰易懂？

（是的，我知道我们可以使用 *important point* 和 ****** HEADER ****** 进行管理，但让我们暂时开箱即用！

我说的是集成在 IDE 中的 RTF 代码编辑器。

4

16 回答 16

12

这是一个有趣的问题，因为除了它现在是否真的是一个好主意之外，它还突破了我们工作方式的界限。

不混合富文本和代码的所有原因都没有解决这是否会帮助任何人的问题 - 是否还有弥补缺点的好处。如果没有人问过这种问题并发明了网络，也许我们都还在使用 gopher。

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

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

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

即使在此处的简短评论中，富文本也很有用，并且当您看不到格式化版本时，Markdown 源仍然是明智的。因此，对于 IDE 来说，一个好的折衷方案是将 Markdown 注释块呈现为富文本，并在光标位置位于注释块中时立即显示 Markdown 源。

于 2009-01-22T06:49:42.597 回答
5

通常，注释代码的想法是解释您的各个例程（或组件部分）打算实现的操作。你不需要用额外的格式和其他人可能认为混乱的东西来标记这些评论。

如果特定部分需要图像、强调或以其他方式需要更深入的解释，则表明需要发行说明或支持文档。开发人员的克星，我知道，但最好保持整洁并易于支持。

于 2009-01-21T23:52:14.610 回答
4

史蒂夫·麦康奈尔（Steve McConell）为复杂格式的评论引用的问题是，由于它们需要进行更多的更改，因此它们更有可能变得陈旧。

如果整个团队都采用了富文本编辑 IDE，或许可以解决这个问题。但是你会开始一种勇敢的、新的代码创建方法，这是大多数团队为了适应当前的最佳实践而明智地倾向于避免的。

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

于 2009-01-21T23:56:21.433 回答
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.
}
于 2009-01-22T00:05:31.337 回答
3

不，因为如果没有您的特殊 IDE 添加，查看您的代码的用户可能无法阅读注释。

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

于 2009-01-21T23:51:07.967 回答
3

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

于 2009-01-21T23:54:39.660 回答
3

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

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

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

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

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

但是，另请参阅“文学编程”。我不知道“文学编程”是什么或本来应该是什么，但它至少在一种狭隘的情况下看起来很有用，也就是说，当你试图写软件时（例如写一篇关于某些软件的文章） .

于 2009-01-21T23:55:44.087 回答
2

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

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

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

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

于 2009-01-21T23:44:25.140 回答
2

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

于 2009-01-21T23:51:11.727 回答
1

我真正希望在评论中出现的唯一富文本是引用其他代码的超链接。使用 Javadoc 样式的注释或仅使用 ctags 很容易做到这一点。

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

于 2009-01-22T00:03:46.630 回答
1

我有点喜欢这个主意。由于注释已经是一种颜色，它可能需要有所限制，而不是真正的富文本，或者很难从代码中挑选出注释。但是，如果它只允许粗体、下划线，也许还有字体大小，那么它会有助于强调您知道代码是杂乱无章的，或者是“永远不要编辑这个”类型的注释。

但是，除非它成为通用且广泛使用的 IDE 的一部分，否则它不会起作用。

于 2009-01-22T00:05:24.583 回答
1

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

于 2009-05-30T08:32:00.343 回答
0

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

于 2009-01-21T23:49:41.977 回答
0

我宁愿只拥有 javadoc 丰富的元素，例如，以富文本方式呈现的类、标题等的链接。这将透明地转换为 javadoc html。我认为这是一个 ide 的好主意。

于 2009-01-22T07:31:33.763 回答
0

已经可以将富文本放入 Python 代码中： sphinx。至少以RST的形式。而且也没有必要为此使用 IDE（尽管我认为一些格式化帮助很有用）。

于 2009-08-22T15:54:08.383 回答
0

早在 NeXT 维护自己的 GCC 私有分支的时候，它就允许在源代码中使用 RTF 标签。不仅在评论中，而且无处不在。它从来都不是一个高度使用的功能，最终被放弃了。一个问题是 RTF 很难用纯文本编辑器阅读，因此只有团队中的每个人都使用支持 RTF 的编辑器（和差异工具）才能工作。

我认为在评论中保留某种格式可能会很有用，但我认为比 RTF 更易于阅读的东西可能是一个更好的主意。Markdown 可能工作得很好。

于 2009-08-22T16:45:24.707 回答