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代碼