记录代码修订

记录代码修订

我对 C++ 程序的几个文件进行了修改。我想在一份漂亮的 LaTeX 报告中记录这些更改,准确展示我修改了什么并解释我修改的原因。

由于有相当多的代码行发生了变化,因此手动浏览所有代码、复制粘贴相关部分并添加注释并不是一个真正的选择。

我的问题是:

  • 您将如何制作这样的文档,最好使用颜色或一些标记来清楚地显示差异?
  • 您会并排显示代码版本吗,或者更确切地说显示一种差异日志?
  • 您会在哪里添加评论?

我正在考虑使用终端 git diff 颜色输出作为基础,以某种方式让 LaTeX 排版它并添加我的评论。

答案1

我同意@hraish-kumar关于在代码中嵌入注释的建议。但如果你想比较分支或提交git存储库中的分支或提交,你可能需要查看这个答案如何在 git 中使用 latexdiff

答案2

这不是你想要的答案。但由于我想展示一个截图,所以我(误)使用了答案。此外,这个问题现在已经很老了。

如果你想展示差异,那么我建议你看看免费软件WinMerge。以下是截图这里

截屏

您可以通过多种方式轻松地显示差异:

  • 添加的内容(屏幕截图中为灰色)
  • 发生了哪些变化(屏幕截图中黄色部分)
  • 已删除的内容(屏幕截图中为灰色)

也许您可以使用不同的屏幕截图并用您的想法进行注释。

答案3

我强烈建议将注释嵌入到代码中,而不是放在单独的文档中。不可避免的是,当需要修改代码时,您或继承代码的人将无法找到您用于注释的任何外部文档。此外,如果它们引用模块名称和行号之类的内容,那么随着时间的推移,这些内容可能会全部更改。是的,公式在 LaTeX 中看起来漂亮得多,但更实际的做法是使用丑陋但完全可访问的注释。

现在,如果你想做一些事情来补充代码中的注释,比如向管理层展示或用于教育,那么你的方法可能会奏效。差异是一个很好的起点,但它们似乎总是需要一些后续清理。此外,它们需要更多的解释,比如“添加的代码”、“修改的代码”和“删除的代码”等字样。我会将代码放在与你添加的注释不同的框架中。

相关内容