xml文档包含html代码

There are a plethora of acronyms when it comes to software development. KISS, DRY, SOLID… and so on and so forth. But, when it comes to documenting or commenting your code, there is no simple catchphrase.

关于软件开发，有很多首字母缩写词。 吻，干，固体……等等。 但是，在记录或注释代码时，没有简单的流行语。

Why is that?

这是为什么？

Documentation should be as important to a developer as all other facets of development

文档对于开发人员应该与开发的所有其他方面一样重要

In this article, I’ll argue why documenting your code will lead to becoming a better developer, and will contribute to being a great team member.

在本文中，我将争论为什么记录您的代码将导致成为更好的开发人员，并有助于成为一名出色的团队成员。

没有人有时间 (Ain’t nobody got time for that)

The main reason code goes undocumented is because of time.

代码未记录的主要原因是由于时间原因。

When developing a feature that needs to be completed within a certain time frame, rarely do we have a moment to stop everything and focus on documenting our code.

在开发需要在特定时间范围内完成的功能时，很少有时间停止所有工作并专注于记录我们的代码。

Apart from designing and writing the code itself, we also need to undergo code reviews, automation tests, and add unit tests (to name a few things). Documentation is pretty much left out of the equation.

除了设计和编写代码本身之外，我们还需要进行代码检查，自动化测试和添加单元测试(仅举几例)。 文档几乎不存在。

It is the least thought about detail that can make the most difference in the future.

对细节的最少思考可以在将来发挥最大作用。

No matter what you are developing, chances are that some day you or one of your colleagues will have to revisit it. When that day comes, you will not remember so vividly what you wrote and why.

无论您正在开发什么，都有可能您或您的一位同事有一天不得不重新审视它。 当那一天到来时，您将不会非常清楚地记得自己写的内容和原因。

And if you do remember, there may be some edge cases or specific uses which may not be clearly apparent. The obvious solution is documentation.

而且，如果您还记得，可能会出现一些不太明显的极端情况或特定用途。 显而易见的解决方案是文档编制 。

Taking that extra time to write a proper description of what you worked on will save huge amounts of time in the future.

采取这一额外的时间来写你的工作是什么在将节省大量的时间在未来适当的说明。

Next time someone wants to understand what happens inside your code, all you have to do is point them to the documentation. It will save time for you, since you won’t need to explain things, and it will save time for them, since they won’t be dependent on you.

下次当某人想了解您的代码内部发生了什么时，您所要做的就是将他们指向文档。 这将为您节省时间，因为您不需要解释任何事情，并且会为它们节省时间，因为它们将不再依赖您。

And after all, when you, as a developer, need to understand something about a certain aspect of coding, what do you do?

毕竟，当您作为开发人员需要了解某些方面的编码时，您会怎么做？

? You go to the documentation ?

？ 你去看文档？

好的代码不需要文档 (Good code does not need documentation)

Yeah, I know, I know… well written code, that is concise and well thought out, does not need to be documented. It reads like a story.

是的，我知道，我知道...编写简洁，经过深思熟虑的良好代码，无需记录在案。 它读起来像一个故事 。

While that may be so, it does not forego the need for documentation, and here is why:

尽管可能是这样，但它不会放弃对文档的需求，这就是为什么：

1. We are all too familiar with the robustness of code that comprises a feature. Looking at one section of code, may not make it clear there are other sections that are deeply linked to it.我们都非常熟悉包含功能的代码的健壮性。 仅仅看一段代码，可能还不清楚，还有其他部分与它紧密相关。
2. Every service you create has a unique API to it. Writing how to use that API requires documentation that can be read outside of the code. You do not want to inflate the class itself with details about how to use the API.您创建的每个服务都具有唯一的API。 编写如何使用该API的文档需要在代码之外阅读。 您不想使用有关如何使用API​​的详细信息来使类本身膨胀。
3. Coworkers who work in different departments (who may not be developers) may want to understand what you did and how it works.在不同部门工作的同事(可能不是开发人员)可能想了解您的工作及其工作方式。
4. Just the act itself may cause you to look differently at the code you wrote. Explaining what your code does will cause you to assess the validity of it and to maybe consider changing things if they do not meet your expectations.只是行为本身可能会使您对编写的代码有所不同。 解释代码的作用会使您评估代码的有效性，并在代码不符合您的期望的情况下考虑进行更改。
5. For posterity’s sake为了后代的缘故

如何编写好的文档 (How to write good documentation)

Good documentation is like a good block of code. Short, simple, and easy to understand. Here are a few guidelines you can follow:

好的文档就像一个好的代码块。 简短，简单且易于理解。 您可以遵循以下准则：

• Understand who the documentation is aimed at. Is it only for developers? Is there a broader audience? Understanding this will save you time, since you will know up front how much to elaborate in your explanations.了解文档的目标对象。 仅适用于开发人员吗？ 是否有更广泛的受众？ 了解这一点将节省您的时间，因为您将预先知道要解释的内容。
• Write a short, but descriptive background explaining the main points of what you built. This will help readers understand the purpose of the feature and ascertain its relevance to what they want to know.写一个简短但描述性的背景，解释所构建内容的要点。 这将帮助读者理解功能的目的，并确定其与他们想知道的内容的相关性。
• List and describe the main perspectives of your feature, making sure to point out any dependencies that exist with other features.列出并描述功能的主要观点，并确保指出其他功能存在的任何依赖关系。
• Make sure there is a timestamp, to tell readers the validity of the documentation. Also, if you are using certain libraries, be sure to include their versions as well.确保有时间戳记，以告知读者文档的有效性。 另外，如果您使用的是某些库，请确保也包括它们的版本。
• Be generous with your coding examples, detailing how to properly use the feature you wrote and showcase the expected results.慷慨地编写代码示例，详细说明如何正确使用所编写的功能并展示预期的结果。

例子 (Examples)

To further understand how good documentation looks like, we’ll review some great examples: Mozilla’s Developer Network(MDN), Django and Stripe.

为了进一步了解优质文档的外观，我们将回顾一些出色的示例： Mozilla的开发人员网络(MDN) ， Django和Stripe 。

In MDN’s documentation, you can clearly see that each page starts with a brief explanation about the subject.

在MDN的文档中，您可以清楚地看到每个页面都以关于该主题的简短说明开头。

Then, it proceeds to detail the use cases and methods. Finally, it shows which browsers are compatible with the feature and gives links to relevant material.

然后，它继续详细说明用例和方法。 最后，它显示了哪些浏览器与该功能兼容，并提供了相关资料的链接。

Django’s documentation is very robust. No matter your coding level, they start you off with an overview and tutorials.

Django的文档非常强大。 无论您的编码水平如何，他们都会以概述和教程开始。

Then, they go through each subject, detailing it meticulously, giving short and concise code snippets that demonstrate what needs to be done

然后，他们遍历每个主题，并对其进行细致的详细说明，并给出简短明了的代码段，以说明需要完成的工作

I hope I have managed to stress the importance of documentation and have given you some pointers on how to start documenting your code. If you have an idea for an acronym for documentation, feel free to do so in the comments below.

我希望我能设法强调文档编制的重要性，并为您提供一些有关如何开始编写代码的指南。 如果您有一个文档缩写的想法，请随时在下面的评论中进行。

Maybe KID — Keep It Documented?

也许KID - K EEP 余吨d ocumented？

If you liked this article, clap away so that others can enjoy it as well! ???

如果您喜欢这篇文章，请拍一下，以便其他人也能喜欢它！ ???

翻译自: https://www.freecodecamp.org/news/why-documentation-matters-and-why-you-should-include-it-in-your-code-41ef62dd5c2f/

xml文档包含html代码