latex添加代码注释

Stop me if you’ve heard this one before…

如果您之前听过我的话，请阻止我...

“Good code is self-documenting.”

“好的代码是自我记录。”

In 20+ years of writing code for a living, this is the one phrase I’ve heard the most.

在20多年的代码编写中，这是我最常听到的一句话。

It’s cliché.

这是陈词滥调。

And like many clichés, it has a kernel of truth to it. But this truth has been so abused that most people who utter the phrase have no idea what it really means.

像许多陈词滥调一样，它具有真实性。 但是这个真理已经被滥用了，以至于大多数说这个短语的人都不知道它的真正含义。

Is it true? Yes.

是真的吗 是的 。

Does it mean you should never comment your code? No.

这是否意味着您永远不要注释您的代码？ 不行

In this article we’ll look at the good, the bad, and the ugly when it comes to commenting your code.

在本文中，我们将讨论注释代码时的好，坏和丑陋之处。

For starters, there are really two different types of code comments. I call them documentation comments and clarification comments.

对于初学者来说，实际上有两种不同类型的代码注释。 我称它们为文档注释和澄清注释 。

文档注释 (Documentation Comments)

Documentation comments are intended for anyone who is likely to consume your source code, but not likely to read through it. If you are building a library or framework that other developers will use, you need some form of API documentation.

文档注释适用于可能使用您的源代码但不太可能阅读您的源代码的任何人。 如果要构建其他开发人员将使用的库或框架，则需要某种形式的API文档。

The further removed from the source code your API documentation is, the more likely it is to become outdated or inaccurate over time. A good strategy to mitigate this is to embed the documentation directly into the code and then use a tool to extract it.

您的API文档从源代码中删除的越多，随着时间的推移，它越有可能变得过时或不准确。 减轻这种情况的一种好策略是将文档直接嵌入代码中，然后使用工具将其提取。

Here’s an example of a documentation comment from a popular JavaScript library called Lodash.

这是来自流行JavaScript库Lodash的文档注释示例 。

If you compare these comments to their online documentation, you’ll see it’s an exact match.

如果将这些评论与他们的在线文档进行比较 ，您会发现它是完全匹配的。

If you write documentation comments you should ensure that they follow a consistent standard and that they are easily distinguishable from any inline clarification comments you may also want to add. Some popular and well supported standards and tools include JSDoc for JavaScript, DocFx for dotNet, and JavaDoc for Java.

如果您编写文档注释，则应确保它们遵循一致的标准，并且易于与您可能还想添加的任何在线澄清注释区分开。 一些受欢迎且受到良好支持的标准和工具包括JavaScript的JSDoc ，dotNet的DocFx和Java的JavaDoc 。

The downside of these kinds of comments is that they can make your code very “noisy” and harder to read for anyone who is actively involved in maintaining it. The good news is that most code editors support “code folding” which allows us to collapse the comments so we can focus on the code.

这些注释的缺点是，它们会使您的代码非常“嘈杂”，而对于任何积极参与维护代码的人来说，它们都更难阅读。 好消息是，大多数代码编辑器都支持“代码折叠”，这使我们可以折叠注释，以便我们专注于代码。

澄清评论 (Clarification comments)

Clarification comments are intended for anyone (including your future self) who may need to maintain, refactor, or extend your code.

澄清注释适用于可能需要维护，重构或扩展您的代码的任何人(包括您将来的自己)。

Often, a clarification comment is a code smell. It tells you that your code is too complex. You should strive to remove clarification comments and simplify the code instead because, “good code is self-documenting.”

通常，澄清注释是代码的味道。 它告诉您代码太复杂。 您应该努力删除澄清注释并简化代码，因为“好的代码是自我记录的”。

Here’s an example of a bad — though very entertaining — clarification comment.

这是一个不好的澄清示例 ，尽管很有趣。

/*  * Replaces with spaces  * the braces in cases  * where braces in places  * cause stasis.**/ $str = str_replace(array("\{","\}")," ",$str);

Rather than decorating a slightly confusing statement with a clever rhyme — in amphibrach dimeter, no less — the author would have been far better off spending time on a function that makes the code itself easier to read and understand. Maybe a function named, removeCurlyBraces called from another function named sanitizeInput?

与其用灵巧的韵律来修饰一个稍微令人困惑的语句( 至少用amphibrach dimeter来装饰) ，作者最好花时间在使代码本身更易于阅读和理解的函数上。 也许是从另一个名为sanitizeInput函数调用的，名为removeCurlyBraces函数？

Don’t get me wrong, there are times — especially when you are slogging through a crushing workload — where injecting a bit of humor can be good for the soul. But when you write a funny comment to make up for bad code, it actually makes people less likely to refactor and fix the code later.

别误会我的意思，有时候，尤其是当您在繁重的工作量中苦苦挣扎时，注入一点幽默可能对灵魂有益。 但是，当您编写有趣的注释来弥补错误的代码时，实际上会使人们不太可能在以后重构和修复代码。

Do you really want to be the one responsible for robbing all future coders of the joy of reading that clever little rhyme? Most coders would chuckle and move on, ignoring the code smell.

您是否真的想成为一名负责抢劫所有未来编码人员的人，以使他们阅读这种聪明的小韵律？ 大多数编码人员会轻笑并继续前进，而忽略了编码的气味。

There are also times when you come across a comment that is redundant. If the code is already simple and obvious, there’s no need to add a comment.

有时您会遇到多余的评论。 如果代码已经很简单明了，则无需添加注释。

Like, don’t do this nonsense:

就像，不要胡说八道：

/*set the value of the age integer to 32*/int age = 32;

Still, there are times when no matter what you do to the code itself, a clarification comment is still warranted.

尽管如此，有时无论您对代码本身做什么，仍需要澄清说明。

Usually this happens when you need to add some context to a non-intuitive solution.

通常，当您需要向非直观解决方案中添加一些上下文时，就会发生这种情况。

Here’s a good example from Lodash:

这是Lodash的一个很好的例子：

function addSetEntry(set, value) {     /*    Don't return `set.add` because it's not chainable in IE 11.  */    set.add(value);      return set;  }

There are also times when — after a lot of thought and experimentation — it turns out that the seemingly naive solution to a problem is actually the best. In those scenarios it is almost inevitable that some other coder will come around thinking they are much smarter than you are and start messing with the code, only to discover that your way was the best way all along.

有时，经过大量的思考和实验，事实证明，似乎天真的解决问题的方法实际上是最好的。 在这些情况下，几乎不可避免地会有其他一些编码器出现，以为它们比您聪明得多，并开始弄乱代码，只是发现您的方式一直是最好的方式。

Sometimes that other coder is your future self.

有时，其他编码员是您未来的自我。

In those cases, it’s best to save everyone the time and embarrassment and leave a comment.

在这种情况下，最好节省每个人的时间和尴尬并发表评论。

The following mock-comment captures this scenario perfectly:

以下模拟注释完美地捕获了这种情况：

/**Dear maintainer: Once you are done trying to 'optimize' this routine,and have realized what a terrible mistake that was,please increment the following counter as a warningto the next guy: total_hours_wasted_here = 42**/

Again, the above is more about being funny than being helpful. But you SHOULD leave a comment warning others not to pursue some seemingly obvious “better solution,” if you’ve already tried and rejected it. And when you do, the comment should specify what solution you tried and why you decided against it.

同样，以上内容是关于有趣而不是有所帮助。 但是您应该发表评论，警告其他人，如果您已经尝试并拒绝了它，则不要追求一些看似明显的“更好的解决方案”。 并且，当您这样做时，注释应指定您尝试了哪种解决方案以及为什么反对该解决方案。

Here’s a simple example in JavaScript:

这是JavaScript中的一个简单示例：

/* don't use the global isFinite() because it returns true for null values*/Number.isFinite(value)

丑陋的 (The Ugly)

So, we’ve looked at the good and the bad, but what about the ugly?

因此，我们研究了好与坏，但是丑陋呢？

Unfortunately, there are times in any job where you’ll find yourself frustrated and when you write code for a living, it can be tempting to vent that frustration in code comments.

不幸的是，在任何工作中，有时您会发现自己感到沮丧，而当您以谋生为目的编写代码时，可能很想在代码注释中消除这种沮丧。

Work with enough code bases and you’ll come across comments that range from cynical and depressing to dark and mean spirited.

使用足够的代码库，您会遇到各种评论，从愤世嫉俗和沮丧到沉闷和刻薄。

Things like the seemingly harmless…

貌似无害的事情……

/*This code sucks, you know it and I know it.  Move on and call me an idiot later.*/

…to the downright mean

…… 直率的意思

/* Class used to workaround Richard being a f***ing idiot*/

These things may seem funny or may help release a bit of frustration in the moment, but when they make it into production code they end up making the coder who wrote them and their employer look unprofessional and bitter.

这些事情看似很有趣，或者可能会在瞬间缓解一些挫败感，但是当他们将其纳入生产代码时，最终使编写这些代码的程序员和他们的雇主显得不专业且痛苦。

Don't do this.

不要这样

If you enjoyed this article, please smash the applause icon a bunch of times to help spread the word. And if you want to read more stuff like this, please sign up for my weekly Dev Mastery newsletter below.

如果您喜欢这篇文章，请多次敲击掌声图标，以帮助宣传。 如果您想类似的内容，请在下面注册我的每周开发精通通讯。

翻译自: https://www.freecodecamp.org/news/code-comments-the-good-the-bad-and-the-ugly-be9cc65fbf83/

latex添加代码注释