xml文档包含html代码_为什么文档很重要,以及为什么应将其包含在代码中

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

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.mzph.cn/news/393617.shtml

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

python 版本分布式锁

此文章,实现python 版本的分布式锁,java版本的可以使用curator很容易实现,python版本如下在做分布式系统开发的时候,分布式锁可以说是必需的一个组件。最近做了一些调研和尝试,经过对比,基于ZooKeeper的分布…

JavaScript数组(2)---遍历/迭代方法 8种

最近工作中经常涉及到数据的处理,数组尤其常见,经常需要对其进行遍历、转换操作,网上的文章零零散散,不得已自己又找出红宝书来翻出来看,顺便记一笔,便于以后查询。 数组常用的方法 ECMAScript5为数组定义了…

用例设计:思维导图orExcel

一、 某次紧急发版时使用思维导图来进行了用例的设计,很被导图多分支罗列、在单一分支上层层递进设计模式的吸引,最终看到由版本主题开枝散叶衍发出的结构性用例时非常开心。从此,几个版本的迭代都使用思维导图进行用例设计。 然而部门制度关…

class对象和class文件_Class文件格式

我们知道Java是一门跨平台的语言,我们编写的Java代码会被编译成中间class文件以让Java虚拟机解析运行。而Java虚拟机规范仅仅描述了抽象的Java虚拟机,在实现具体的Java虚拟机时,仅指出了设计规范。Java虚拟机的实现必须体现规范中的内容&…

2018计算机应用基础考试6,2018结构工程师《计算机应用基础》试题(6)

大家做好准备迎接2018考试了吗?出国留学网为您整理了“2018结构工程师《计算机应用基础》试题(6)”,跟着出国留学网来了解一下吧。要相信只要自己有足够的实力,无论考什么都不会害怕!2018结构工程师《计算机应用基础》试题(6)1、下列存储器中&#xff0…

leetcode1282. 用户分组(贪心算法)

有 n 位用户参加活动,他们的 ID 从 0 到 n - 1,每位用户都 恰好 属于某一用户组。给你一个长度为 n 的数组 groupSizes,其中包含每位用户所处的用户组的大小,请你返回用户分组情况(存在的用户组以及每个组中用户的 ID&…

mysql解锁_mysql 解锁

show OPEN TABLES where In_use > 0;show processlist;show status like Table%;show status like %lock%;show OPEN TABLES where In_use > 0;//1.查看当前数据库锁表的情况SELECT * FROM information_schema.INNODB_TRX;//2.杀掉查询结果中锁表的trx_mysql_…

强制换行和禁止换行

强制换行:word-break: break-all; 只对英文起作用,以字母作为换行依据word-wrap: break-word; 只对英文起作用,以单词作为换行依据white-space: pre-wrap; 只对中文起作用,强制换行禁止换行:white-space: now…

构建自己的简单微服务架构(开源)

构建自己的简单微服务架构(开源) 原文:构建自己的简单微服务架构(开源)前言 本篇仅作引导,内容较多,如果阅读不方便,可以使用电脑打开我们的文档官网进行阅读。如下图所示&#…

职业生涯愿景计算机,职业生涯愿景

《职业生涯愿景》由会员分享,可在线阅读,更多相关《职业生涯愿景(10页珍藏版)》请在人人文库网上搜索。1、职业生涯愿景职业生涯愿景设备安装技术是掌握本专业必需的基本理论知识,具有设备制造、安装、调试、管理、设计。施工方案编制的专业技…

leetcode881. 救生艇(贪心算法加双指针)

第 i 个人的体重为 people[i],每艘船可以承载的最大重量为 limit。 每艘船最多可同时载两人,但条件是这些人的重量之和最多为 limit。 返回载到每一个人所需的最小船数。(保证每个人都能被船载)。 示例 1: 输入:people [1,2]…

react避免子组件渲染_如何与React一起使用正确的方法来避免一些常见的陷阱

react避免子组件渲染One thing I hear quite often is “Let’s go for Redux” in our new React app. It helps you scale, and the App data shouldn’t be in React local state because it is inefficient. Or when you call an API and while the promise is pending, th…

[转载]Spring配置文件详解一:

2019独角兽企业重金招聘Python工程师标准>>> 原文地址&#xff1a;Spring配置文件详解一&#xff1a;<context:annotation-config/>与<context:component-scan base-package"com.xx 作者&#xff1a;爱情随遇而安 <context:annotation-config/>…

mysql 8.0.16修改root密码_mysql 8.0.16 winx64及Linux修改root用户密码 的方法

连接数据库等基础操作请自行解决哈&#xff0c;本篇是重点记录如何改密码。一、查询用户密码:查询用户密码命令&#xff1a;select host, user, authentication_string from mysql.user ;host&#xff1a;允许用户登录的ip‘位置%表示可以远程&#xff1b;user&#xff1a;当前…

舞台设计

舞台设计 #include<iostream> #include<cstring> #include<algorithm> #include<cmath> #include<cstdio> #include<queue> using namespace std;int ucol[1005],dcol[1005],lrow[1005],rrow[1005]; int numr[1005],numc[1005]; int a[100…

LoadRunner11支持的浏览器小结

LoadRunner11支持的浏览器小结转载于:https://www.cnblogs.com/zwh-Seeking/articles/11060154.html

手机计算机的隐藏小技巧,涨知识!MIUI计算器原来有这么多隐藏小技巧,最后一个绝对想不到...

原标题&#xff1a;涨知识&#xff01;MIUI计算器原来有这么多隐藏小技巧&#xff0c;最后一个绝对想不到计算器除了我们需要进行日常的计算以外&#xff0c;几乎是用不到的。但是MIUI中的计算器与普通计算器可不同&#xff0c;里面的隐藏小技巧足以让你震惊到&#xff0c;那么…

如何使用JavaScript中的工厂函数构建可靠的对象

Discover Functional JavaScript was named one of the best new Functional Programming books by BookAuthority!“发现功能JavaScript”被BookAuthority评为最佳新功能编程书籍之一 &#xff01; I suggest to take into consideration these ideas for building reliable …

leetcode99. 恢复二叉搜索树(优先队列)

二叉搜索树中的两个节点被错误地交换。请在不改变其结构的情况下&#xff0c;恢复这棵树。示例 1:输入: [1,3,null,null,2]1/3\2输出: [3,1,null,null,2]3/1\2代码 /*** Definition for a binary tree node.* public class TreeNode {* int val;* TreeNode left;* …

Android零基础入门第83节:Activity间数据传递方法汇总

2019独角兽企业重金招聘Python工程师标准>>> 在Activity间传递的数据一般比较简单&#xff0c;但是有时候实际开发中也会传一些比较复杂的数据&#xff0c;本节一起来学习更多Activity间数据的传递。 一、常用数据类型 在前面几节我们只学习了一些常用类型的数据传递…