多个文档放到一个文档代码_如何停止强调您的代码文档

最新推荐文章于 2020-12-08 14:16:14 发布

weixin_26752759

最新推荐文章于 2020-12-08 14:16:14 发布

阅读量133

点赞数

文章标签： java python js javascript vue ViewUI

原文链接：https://levelup.gitconnected.com/how-to-stop-stressing-over-your-code-documentation-f1e92bc5fa8

版权

多个文档放到一个文档代码

I am a new convert to code documentation.

我是一个新的转换为代码文档。

I neglected code documentation for way too many of my programming years. It stressed me out. I avoided it like kids avoided picking me in basketball pick-up games as a kid.

我在编程的很多年中都忽略了代码文档。它使我紧张。我避免了这种情况，就像孩子们小时候避免在篮球比赛中接我一样。

I was terrified that I was going to do it wrong or that it wouldn’t make any sense or that I was going to be ‘found out’ as a terrible programmer. I hid under the excuse that good code should self-document. I do agree that other engineers should easily know what good code is doing but we need to also understand the wonderfully existential question of “Why it exists.”

我很害怕自己做错了，或者没有任何意义，或者我被一个可怕的程序员“发现”了。我以好的代码应该自我记录为借口来躲藏。我确实同意其他工程师应该容易地知道好的代码在做什么，但是我们也需要理解奇妙的存在性问题“为什么存在”。

After too many years of neglect, I was forced to face the reality that my code needed documentation. It needed it badly.

经过多年的忽视，我被迫面对这样一个现实，即我的代码需要文档。它非常需要它。

不知所措 (Overwhelmed by Documentation)

I decided to confront my documentation fears with a cowardly advance. I inched deeper into the freezing pool of documentation one step at a time.

我决定以怯ward的态度面对我的文档恐惧。我一次一步地深入文档的冻结库。

I started out small.

我从小开始。

I added 1 line doc blocks that described my code functions & classes in single sentences. I moved further into the pool by adding documentation to my variables & function parameters and eventually I was fully submersed through documenting examples and helping the future me understand why I took this path and what I want to do in the future.

我添加了1行doc块，用单句话描述了我的代码功能和类。通过向变量和函数参数添加文档，我进一步进入了池中，最终我被文档示例完全淹没，并帮助未来我理解了为什么走这条路以及将来想要做什么。

Now I’m belly-flopping my way into the pool of documentation before I even start writing any code.

现在，我什至在开始编写任何代码之前就开始尝试进入文档库。

I graduated from the no documentation camp into the belief that good documentation brings the best code to life. I am no longer petrified at the thought my functions, classes and if blocks may need a doc block.

我从没有文档的阵营毕业，坚信好的文档可以带来最好的代码。我不再对我的功能，类以及是否需要使用doc块感到震惊。

My fear of documentation no longer owns me. My code eats doc blocks as Popeye eats spinach. Code Documentation is now the V8 to my work.

我对文档的恐惧不再归我所有。我的代码吃了文档块，而大力水手吃了菠菜。代码文档现在是我工作的V8。

It wasn’t an easy switch. I didn’t just wake up one day with superhuman code documentation superpowers gifted to me.

这不是一件容易的事。有一天，我不仅拥有超人代码文档的超能力，而且还拥有超能力。

It was a process that I took a step at a time.

这是我一次迈出的一步。

停止思考代码文档 (Stop Overthinking Your Code Documentation)

Let’s start with the obvious.

让我们从显而易见的地方开始。

Documentation isn’t prose to impress your high school English teacher. It has a purely functional purpose. It doesn’t need wit. It can and should have personality but that is secondary. It has a singular and simple functional purpose for existence. Documentation never needs to belly gaze asking itself, “What is my purpose in life.”

文档并不能使您的高中英语老师印象深刻。它具有纯粹的功能目的。它不需要机智。它可以而且应该具有个性，但这是次要的。它具有存在的单一且简单的功能目的。文档永远不需要needs心自问，“我的人生目标是什么”。

It is simple.

很简单。

Documentation exists to express the reason for the code’s existence in a human readable language. That is it. It needs to be succinct so that your future self can read the documentation and understand what you were smoking when you wrote the code.

存在文档以人类可读的语言表达代码存在的原因。这就对了。它必须简洁明了，以便您将来的自己可以阅读文档并了解编写代码时所吸烟的内容。

Don’t overthink code documentation.

不要想太多代码文档。

You may believe I’m an odd man to write engineers overthink code documentation. It is true that I am odd but it is also true that I am right. You are overthinking your documentation if you look at your functions for more than a few moments wondering what to document.

您可能会相信我是一个奇怪的人，他们会写工程师过分考虑代码文档。我很奇怪，但我也很正确。如果您花了超过一会儿时间想知道要记录什么内容，那么您就会过度考虑文档。

Just write something.

只是写点东西。

Documentation doesn’t have to be perfect. It doesn’t have to be coherent. It doesn’t have to be complete and it can be wrong. Code documentation doesn’t exist on stone tablets that must be hung as law for everyone to follow.

文档不一定是完美的。它不必是连贯的。它不一定是完整的，而且可能是错误的。石碑上没有代码文档，必须将石碑作为法律加以悬挂，以供所有人遵循。

You can, should and must update your documentation.

您可以，应该并且必须更新您的文档。

Good documentation is the conversation between you and the code. You begin the conversation with certain assumptions. As you write your code, the conversation morphs into new directions. Tangents happen. The best conversations flow into a natural progression. This is the same for code and documentation.

好的文档是您与代码之间的对话。您以某些假设开始对话。在编写代码时，对话会演变为新的方向。切线发生。最好的对话自然而然地发展。对于代码和文档，这是相同的。

Good documentation is the conversation between you and the code.

好的文档是您与代码之间的对话。

Don’t force documentation into a perfect state because this will force your code into a dangerously inflexible state. Allow it to breathe and change as the conversation with yourself and your code changes.

不要强迫文档进入理想状态，因为这会迫使您的代码陷入危险的僵化状态。随着与您自己的对话以及您的代码的更改，让它呼吸和更改。

在编写代码之前先从文档开始 (Start With the Documentation Before You Write the Code)

What do you when you are ready to start programming a new feature?

当您准备开始编写新功能时，您会做什么？

My guess is that you open up the editor and either begin brain dumping the code in your head or take the test driven approach and start writing your tests.

我的猜测是，您打开编辑器，或者开始脑子里转储代码，或者采用测试驱动的方法并开始编写测试。

Both directions are wrong.

两个方向都是错误的。

Write the functional story of what you are doing in a human language before you start on any code or tests.

在开始任何代码或测试之前，请以人类语言写出您正在做的功能性故事。

I am not referencing functional requirements are architectural diagrams. I assume you’ve properly broke down the project. You already have the high level business and functional understanding of what you are doing. If not, then you need to be reading another article about proper project architecture and come back to this one.

我所引用的功能需求不是体系结构图。我认为您已经正确分解了该项目。您已经对正在做的事情有较高的业务和功能理解。如果不是，那么您需要阅读另一篇有关适当的项目体系结构的文章，然后再回到这篇文章。

You need to open up your IDE or text editor and write the story of what you are going to program before you write a line of code.

在编写一行代码之前，您需要打开IDE或文本编辑器并编写要编写程序的故事。

Document why an if statements exists and the problem it solves before you write the if block.
在编写if块之前，请记录为什么存在if语句及其解决的问题。
Explain the backstory of why you want to add this new function or class. Let me know what you want to accomplish and when I should and shouldn’t use the new function.
解释为什么要添加此新函数或类的背景知识。让我知道您想完成什么以及何时应该使用新功能。
Describe what that new constant does and it’s purpose for living.
描述新常量的作用及其生存目的。

Your code should never be added to empty files. The code should fill in the blanks of well documented instructions.

您的代码永远不应添加到空文件中。该代码应填入有据可查的说明的空白处。

好的文档可以回答《准则》的现有问题 (Good Documentation Answers the Existential Questions for The Code)

Honestly, think of your code as a 20 year old college student flunking their way through Intro to Philosophy.

老实说，将您的代码想像成一个20岁的大学生，在《哲学概论》中步履蹒跚。

It wants to know why it exists? What is its purpose in life? How will it know if it has any value? Does anyone care about it?

它想知道它为什么存在？它的人生目的是什么？如何知道它是否有价值？有人在乎吗？

This is why you write documentation.

这就是编写文档的原因。

You want to let your code know that it has a purpose for existence and that it doesn’t need to spend the next 10 years living in your basement wondering what job is right for them.

您想让您的代码知道它具有生存的目的，并且不需要在接下来的10年里住在您的地下室中，而去想一想适合他们的工作。

文档不应该使您不知所措。它应该可以帮助您了解您想做什么 (Documentation Should Not Overwhelm You. It Should Help You Understand What You Want to Do)

Don’t overwhelm yourself with code documentation. It is not an exercise in grammar and technical ability. Good engineers aren’t going to review your documentation and base your entire worth on a poorly constructed doc block. Bad engineers will. But who cares as they are bad engineers.

不要让代码文档不知所措。这不是语法和技术能力的练习。好的工程师不会去审查您的文档，而会将您的全部价值建立在结构不良的文档块上。不好的工程师会。但是谁在乎，因为他们是坏工程师。

Make a decision to become a story teller where the code fills in the blanks. Your documentation is the narrator and directs the story to its final resolution.

决定成为故事讲述人，代码将填补其中的空白。您的文档是讲述人，并将故事引导到最终解决方案。