你如何标记代码以便稍后回来处理它？

Posted 2023-02-21

【中文标题】你如何标记代码以便稍后回来处理它？

【英文标题】：How do you flag code so that you can come back later and work on it?

【发布时间】：2010-09-25 00:33:56

【问题描述】：

在 C# 中，我使用 #warning 和 #error 指令，

#warning This is dirty code...
#error Fix this before everything explodes!

这样，编译器会让我知道我还有工作要做。你用什么技术来标记代码，这样你就不会忘记它？

【参考方案1】：

在您的代码库中散布信息量不足的 TODO 可能不是一个好主意，尤其是当您随着时间的推移有多个贡献者时。这对于新手来说可能会很困惑。但是，在我看来，在实践中运作良好的是说明作者和 TODO 的编写时间，带有标题（最多 50 个字符）和更长的正文。

无论您在 TODO cmets 中包含什么内容，我都建议您系统地跟踪它们。例如，有一项服务根据git blame (http://www.tickgit.com) 检查存储库中的 TODO cmets。

我开发了自己的命令行工具，以使用此处答案 (https://github.com/mristin/opinionated-csharp-todos) 中的想法来强制执行 TODO cmets 的一致样式。将它集成到持续集成中相当容易，这样每次推送到主服务器时都会重新生成任务列表。

当您在与其他人的会议中讨论 TODO 时，当您想通过电子邮件共享它时，将任务列表与您的 IDE 分开也是有意义的等。

【参考方案2】：

这是我使用的临时评论标签列表：

//+TODO  Usual meaning.
//+H     Where I was working last time.
//+T     Temporary/test code.
//+B     Bug.
//+P     Performance issue.

表示不同的优先级，例如：//+B vs //+B+++

优点：

易于从代码中搜索/删除（查找//+）。 易于按优先级过滤，例如：搜索//+B 查找所有错误，搜索//+B+++ 仅获得高优先级。

可用于 C++、C#、Java、...

为什么使用//+ 符号？因为+ 符号看起来有点像t，用于临时。

注意：这不是标准推荐，只是个人推荐。

【参考方案3】：

用 // TODO、// HACK 或其他将显示在 Visual Studio 任务窗格中的注释标记标记它们。

见Using the Task List。

【讨论】：

我以前也这样做过 //TODO:，但有时我会忘记检查任务窗格。

@Jon T：抛出新的 NotImplementedException() 怎么样。这对你有帮助吗？我有时也会这样做。

TODO 在 vi​​m 中出现了令人讨厌的棕色背景 - 视觉代码气味

@S.Lott：你使用@todo，而不是典型的TODO，有什么特别的原因吗？ （我只是好奇）

我觉得 //BUG 也是有效的

【参考方案4】：

我在我的方法中使用//TODO: //HACK: 和throw new NotImplementedException(); 的组合来表示未完成的工作。另外，我在 Visual Studio 中为不完整的行添加了书签。

【参考方案5】：

这不是一个完美的世界，我们并不总是有无限的时间来重构或思考代码。

我有时会在代码中添加//REVIEW，如果我想稍后再返回的话。即代码正在运行，但可能不相信这是最好的方法。

// REVIEW - RP - Is this the best way to achieve x? Could we use algorithm y?

//REFACTOR 也是如此

// REFACTOR - should pull this method up and remove near-dupe code in XYZ.cs

【参考方案6】：

我是一名 C++ 程序员，但我想我的技术可以很容易地用 C# 或任何其他语言实现：

我有一个ToDo(msg) 宏，它扩展为在本地范围内构造一个静态对象，其构造函数输出一条日志消息。这样，当我第一次执行未完成的代码时，我会在日志输出中收到提醒，告诉我不能再推迟任务。

看起来像这样：

class ToDo_helper

  public:
     ToDo_helper(const std::string& msg, const char* file, int line)
     
       std::string header(79, '*');
       Log(LOG_WARNING) << header << '\n'
                        << "  TO DO:\n"
                        << "    Task:  " << msg << '\n'
                        << "    File:  " << file << '\n'
                        << "    Line:  " << line << '\n'
                        << header;
     
;

#define TODO_HELPER_2(X, file, line) \
  static Error::ToDo_helper tdh##line(X, file, line)

#define TODO_HELPER_1(X, file, line) TODO_HELPER_2(X, file, line)
#define ToDo(X) TODO_HELPER_1(X, __FILE__, __LINE__)

...你像这样使用它：

 void some_unfinished_business() 
   ToDo("Take care of unfinished business");
 

【讨论】：

哇，先生好样的

【参考方案7】：

如果是long term technical debt，你可以这样评论：

// TODO: This code loan causes an annual interest rate of 7.5% developer/hour. Upfront fee as stated by the current implementation. This contract is subject of prior authorization from the DCB (Developer's Code Bank), and tariff may change without warning.

... 错误。我想 TODO 会做到这一点，只要你不简单地忽略它们。

【参考方案8】：

除了关闭“TODO:”注释之外，许多 IDE 还关闭了“TASK:”注释。一些 IDE 甚至允许您配置自己的特殊标识符。

【参考方案9】：

正如大多数程序员在这里所做的那样，我使用 TODO cmets。另外，我使用 Eclipse 的任务界面Mylyn。当任务处于活动状态时，Mylyn 会记住我打开的所有资源。这样我就可以追踪了

我必须在文件的哪个位置（以及什么）做某事， 我必须在哪些文件中进行操作，并且 它们与什么任务相关。

【参考方案10】：

我也使用 TODO：cmets。我理解他们很少真正得到修复的批评，并且最好将它们报告为错误。但是，我认为这忽略了几点：

我在繁重的开发过程中最常使用它们，那时我不断地重构和重新设计事物。所以我一直在看着他们。在这种情况下，他们中的大多数实际上确实得到了解决。此外，搜索 TODO 也很容易：确保我没有遗漏任何内容。

这对于阅读您的代码的人非常有帮助，可以了解您认为写得不好或被盗用的地方。如果我正在阅读不熟悉的代码，我倾向于寻找组织模式、命名约定、一致的逻辑等。如果为了权宜之计不得不违反这种一致性一两次，我宁愿看到一个说明。这样我就不会浪费时间去寻找没有逻辑的地方。

【参考方案11】：

我发现这三种不同的方法有助于标记需要解决的问题。

在需要查看的代码旁边放置一个注释标记。大多数编译器可以识别常见的标志并以有组织的方式显示它们。通常你的 IDE 有一个专门为这些标志设计的监视窗口。最常见的注释标志是：//TODO 您将如何使用它：

//TODO：在发布之前修复它。这会导致访问冲突，因为它正在使用尚未创建的内存。

在发布前标记需要解决的问题的一种方法是创建一个无用的变量。如果您有未使用的变量，大多数编译器都会警告您。以下是您可以如何使用此技术：

int This_Is_An_Access_Violation = 0;

IDE 书签。大多数产品都会提供一种在您的代码中放置书签以供将来参考的方法。这是一个好主意，只是它只能被您看到。当您共享代码时，大多数 IDE 不会共享您的书签。您可以查看 IDE 的帮助文件系统，了解如何使用它的书签功能。

【参考方案12】：

我使用 //FIXME: xxx 表示损坏的代码，使用 //CHGME: xxx 表示需要注意但有效的代码（可能仅在有限的上下文中）。

【参考方案13】：

//TODO: Finish this

如果你使用 VS，你可以在 Tools>Options>Environment>Task List 下设置你自己的 Task Tags

【参考方案14】：

// TODO: <explanation>

如果这是我还没有开始实施并且不想忘记的事情。

// FIXME: <explanation>

如果它是我认为不合适的东西，并且想稍后再回来或让其他人看到它。

从未想过#error/#warning 选项。这些也可以派上用场。

【参考方案15】：

我使用 // TODO: 或 // HACK: 来提醒某些事情未完成，并附上解释原因的注释。 由于时间限制，我经常（读“很少”）回去完成这些事情。 但是，当我查看代码时，我记录了未完成的内容，更重要的是为什么。

我经常在一天或一周结束时使用的另一条评论：

// 从这里开始克里斯

^^^^^^^^^^^^^^^^^^^^ 告诉我我在哪里停下来，这样我就可以在星期一早上尽量减少我的引导时间。

【参考方案16】：

如果我必须在更改过程中放弃所有内容，那么

#error finish this

如果这是我以后应该做的事情，它会进入我的错误跟踪器（用于所有任务）。

【参考方案17】：

我真正喜欢的一种方法是“Hack Bombing”，正如 Oren Eini here 所展示的那样。

try

   //do stuff
   return true;

catch // no idea how to prevent an exception here at the moment, this make it work for now...

  if (DateTime.Today > new DateTime(2007, 2, 7))
    throw new InvalidOperationException("fix me already!! no catching exceptions like this!");
  return false;

【讨论】：

+1 出于幽默价值，尽管这绝对是可怕的！

【参考方案18】：

Todo 评论也是如此。

我们还添加了一个特殊的关键字 NOCHECKIN，我们在源代码控制系统中添加了一个提交挂钩（至少使用 cvs 或 svn 很容易做到），它会扫描所有文件并拒绝签入文件如果它在任何地方找到文本 NOCHECKIN。

如果您只是想测试某些东西并确保它不会被意外签入（在提交到源代码控制的所有内容的差异期间通过监视的眼睛），这将非常有用。

【参考方案19】：

'To do' cmets 在理论上很好，但在实践中却不是很好，至少在我的经验中是这样。如果您要被拉走足够长的时间以需要它们，那么它们往往会被遗忘。

我赞成 Jon T 的一般策略，但我通常只是暂时简单地破坏代码 - 我经常插入一个故意未定义的方法引用，让编译器提醒我需要返回的内容：

PutTheUpdateCodeHere();

【参考方案20】：

gvim 用黄色突出显示“// XXX”和“// TODO”，当我第一次用这种方式标记一些代码以提醒自己回到它时，这让我很惊讶。

【参考方案21】：

添加一个处于禁用状态的测试。它们出现在所有构建报告中。

如果这不起作用，我会提交一个错误。

特别是，我没有看到 TODO cmets 的数量以任何有意义的方式减少。如果我写评论的时候没有时间做，我不知道为什么我以后会有时间。

【参考方案22】：

//TODO: 人名 - 请解决这个问题。

这是在 Java 中，然后您可以查看 Eclipse 中的任务，这些任务将找到对该标记的所有引用，并且可以按人对它们进行分组，以便您可以将 TODO 分配给其他人，或者只查看您自己的。

【讨论】：

这是一个很酷的主意 - 我从来没有想过在代码中临时分配东西。

谢谢，我们大量使用它来为其他人快速标记代码，这样他们就不必搜索它了。

我们已经这样做了，但是为每个人创建了自定义标签，所以它只是 //NAME: blah blah blah，我们共享 Eclipse 配置

【参考方案23】：

待办事项评论。