综合练习:qq练习_故意练习：我从阅读docco中学到的知识
综合练习:qq练习
by Anthony Ng
由Anthony Ng
故意练习：我从阅读docco中学到的知识 (Deliberate Practice: What I learned from reading docco)
I was browsing through open source projects, trying to find the next one I would study. I came upon underscore and its annotated source code.
我浏览了开源项目，试图找到下一个我要学习的项目。 我遇到了underscore及其带注释的源代码 。
The annotated source code amazed me. On the right side of the page was the source code. On the left side of the page were notes explaining each block of code. This was knowledge that I would not have gotten from reading the source code on my own. I wanted to know what produced this beautiful documentation and found docco.
带注释的源代码使我惊讶。 页面右侧是源代码。 页面左侧是注释，解释每个代码块。 这是我自己阅读源代码所不具备的知识。 我想知道是什么产生了这个漂亮的文档并找到了docco 。
什么是docco？ (What is docco?)
docco is a “literate-programming-style documentation generator.” It is a program which takes your source code and creates annotated documentation.
docco是“文学编程风格的文档生成器”。 这是一个使用您的源代码并创建带注释的文档的程序。
Note that docco only generates the layout of the documentation. The comments from your source code serves as the annotations.
请注意， docco仅生成文档的布局。 源代码中的注释用作注释。
如何使用docco？ (How to use docco?)
I have an amazing function that I want to create documentation for. I included descriptive comments which will act as my annotations.
我有一个很棒的功能，我想为其创建文档。 我包括了描述性评论，这些评论将作为我的注释。
To use docco, I will install it locally with npm install — save-dev docco.
要使用docco ，我将使用npm install — save-dev docco在本地安装它。
The docco command accepts file names, which it will generate documentation for. My program is saved as app.js, so I will run ./node_modules/.bin/docco app.js.
docco命令接受文件名，它将为其生成文档。 我的程序保存为app.js ，因此我将运行./node_modules/.bin/docco app.js
And that’s all it takes to create annotated source code!
这就是创建带注释的源代码所需的全部！
By default, docco will place all generated documentation into a new docs directory. You can configure docco to use different CSS or different layouts. Check out this linear layout of the annotated code.
默认情况下， docco会将所有生成的文档放置到新的docs目录中。 您可以将docco配置为使用不同CSS或不同的布局。 检查此带注释的代码的linear布局 。
Check out docco’s README.md to see what else you can customize.
查阅docco的README.md ，看看您还可以自定义什么。
I am going to start using docco to start annotating all future Open Source projects that I work through.
我将开始使用docco来注释我将来通过的所有开源项目。
什么是识字编程？ (What is literate programming?)
With literate programming, you want to express your program logic in plain language. A person should be able to read through it like a book and understand what is happening.
对于有文化的编程 ，您想用简单的语言表达程序逻辑。 一个人应该能够像一本书一样阅读它并了解正在发生的事情。
This means that documentation should follow the same order as the program logic, and not the same order as the source code. We write programs in an order that makes our compiler happy. Sometimes, this order is not the same as the logic of our program.
这意味着文档应遵循与程序逻辑相同的顺序，而不应与源代码相同。 我们以使编译器满意的顺序编写程序。 有时，此顺序与我们程序的逻辑不同。
So, docco doesn’t generate literate programming documentation in its truest sense. docco generates its documentation in the same order as its source code. But, I still think that this annotated source code is valuable. Think of it as pseudocode for your code.
因此， docco不会产生最真实的识字编程文档。 docco按照与源代码相同的顺序生成其文档。 但是，我仍然认为此带注释的源代码很有价值。 将其视为代码的伪代码。
拆开东西放回去 (Taking things apart and putting them back together)
When starting to understand a new project, invest time into setting up a feedback loop. It may be setting up the test suite, so that you can edit the source code and see what breaks. It may be finding a quick way to run the source code from your terminal to see your console logs. I would not start browsing the source code until you have a way of creating this feedback loop.
开始了解新项目时，请花时间建立反馈回路。 可能正在设置测试套件，以便您可以编辑源代码并查看有什么问题。 它可能是一种从终端运行源代码以查看控制台日志的快速方法。 在您无法创建反馈循环之前，我不会开始浏览源代码。
This is what makes Test Driven Development so effective and enjoyable for me. You see what your code is doing instantly. Without a feedback loop, you will be coding in the dark.
这就是让测试驱动开发对我如此有效和令人愉快的原因。 您会立即看到代码在做什么。 没有反馈循环，您将在黑暗中编码。
I was running docco’s source code in my terminal by running node docco.js app.js, where app.js was a dummy file. I was able to see the results of my console.log’s by running this command. This is what my beautiful source code looked like, with over 150 lines of my own comments.
我通过运行node docco.js app.js在终端中运行docco的源代码，其中app.js是伪文件。 通过运行此命令，我可以看到console.log的结果。 这就是我漂亮的源代码的样子 ，上面有150行自己的注释。
处理您将定期使用的项目 (Work on projects you will use regularly)
Kent Dodds wrote a great article about contributing to Open Source projects. His suggestion is to only work on projects that you will use regularly. This is how I have chosen the projects I have worked on. I decided to create my own version of docco because it was something that I would want to use myself.
肯特·多德斯(Kent Dodds)写了一篇很棒的文章，介绍了对开源项目的贡献。 他的建议是仅在您将定期使用的项目上工作。 这就是我选择自己从事的项目的方式。 我决定创建自己的docco版本，因为我想自己使用它。
I also decided against using docco itself because its maintenance seemed to be dead. Was the latest commit from over 2 years ago? Are there stale outstanding issues from years ago? Are there a lot of ignored Pull Requests? These are good indicators that this project may be dead or unmaintained.
我还决定不使用docco本身，因为它的维护似乎已经死了。 是2年前的最新提交吗？ 几年前是否有过时的悬而未决的问题？ 是否有很多被忽略的拉取请求？ 这些是表明该项目可能已死或得不到维护的良好指标。
Most importantly, I wanted to create and publish docco-lite for the learning experience.
最重要的是，我想为学习体验创建并发布docco-lite 。
很棒的库也存在于浏览器之外 (Awesome libraries exist outside of the browser as well)
I have concentrated on the front-end world. I know there are no shortages of libraries and frameworks that are available to me. I was ignorant of the amazing libraries available outside of the front-end world.
我专注于前端世界。 我知道不乏可供我使用的库和框架。 我不了解前端世界之外可用的惊人库。
Here are some awesome libraries that docco used.
这是docco使用的一些很棒的库。
1. fs-extra (1. fs-extra)
fs-extra is a beefed up version of the file system (fs) module. It was very cool to create directories and files, instead of creating <div>’s and <h1>’s.
fs-extra是文件系统(fs)模块的增强版本。 创建目录和文件非常酷，而不是创建<d iv> s an d <h1>。
2.指挥官 (2. commander)
commander is a library that creates command-line interfaces.
commander是一个创建命令行界面的库。
3.粉笔 (3. chalk)
chalk lets you style your terminal strings ?
chalk可以让您设置终端字符串的样式吗？
4. Highlight.js (4. highlightjs)
highlightjs can create HTML out of a string of code. With this HTML output, you can add CSS to style your code snippets.
highlightjs可以使用代码字符串创建HTML。 通过此HTML输出，您可以添加CSS来设置代码段的样式。
JavaScript模板 (JavaScript Templates)
In General Assembly’s bootcamp, I learned Handlebars before the fancy Angular/React. Handlebars is a simple JavaScript templating language, which puts JavaScript into your HTML. If you have a simple project, sometimes a simple templating language is enough to get you by. The overhead of using React may not make sense.
在大会的训练营中，我在花哨的Angular / React之前学习了把手。 车把是一种简单JavaScript模板语言，可将JavaScript放入HTML。 如果您有一个简单的项目，有时使用简单的模板语言就足够了。 使用React的开销可能没有意义。
I have worked with React for the past year. The simplicity and power of using JavaScript templates surprised me. The underscore library provides a simple way to use JavaScript templating.
在过去的一年中，我曾与React合作。 使用JavaScript模板的简单性和功能使我感到惊讶。 underscore库提供了一种使用JavaScript模板的简单方法。
If you want to include JavaScript in your template, use <% %>.
如果要在模板中包含JavaScript，请使用<% ％％>。
If you want the JavaScript to render as text, use <%= %> (note the equal (=) sign).
如果希望JavaScript以文本形式呈现，请使用<%= ％>(注意等号(=))。
You can even get fancy and use for-loops with JavaScript templates.
您甚至可以幻想并在JavaScript模板中使用for循环。
Now let’s put it all together using underscore's template method.
现在，让我们使用underscore的template方法将它们放在一起。
We didn’t need webpack, Babel, or the virtual DOM. The good ol’ days of building a webpage ?.
我们不需要webpack，Babel或虚拟DOM。 建立网页的美好时光吗？
建立有价值的公关 (Create valuable PRs)
Contributing to an Open Source project should provide value for someone. You could be helping others by fixing bugs, adding features, or updating documentation. You could be helping yourself by working on a project where you learn something new.
为开源项目做贡献应该为某人提供价值。 您可以通过修复错误，添加功能或更新文档来帮助他人。 您可以通过从事一个学习新知识的项目来帮助自己。
But make sure that the work you are doing is not wasted.
但是请确保您所做的工作没有浪费。
Take a look at the UMD repository.
看一下UMD存储库 。
We can see some Markdown formatting issues in the README.md. This would be a perfect opportunity to create a Pull Request to fix this.
我们可以在README.md中看到一些Markdown格式化问题。 这将是创建请求请求以解决此问题的绝好机会。
But before we do this, let’s check that our efforts are not wasted. Let’s check out the outstanding Pull Requests.
但是在执行此操作之前，让我们检查一下我们的工作是否没有浪费。 让我们检查未完成的请求。
Notice how there are 11 outstanding Pull Requests which fix the same thing.
请注意，有11个未完成的Pull Requests解决了同一问题。
It’s awesome that people care enough about this project to fix its documentation. But creating a 12th Pull Request to fix the README.md isn’t going to help anyone.
人们非常关心这个项目以修复其文档真是太棒了。 但是创建第12个Pull Request来修复README.md不会帮助任何人。
The same can be said before creating a Pull Request to add a new feature or fixing a bug. You should create an issue on Github first. The feature might not be wanted, so the time spent on the Pull Request is a waste. The bug you found might actually be a bug in your own code, rather than a bug in the library’s source code.
在创建请求请求以添加新功能或修复错误之前，可以这样说。 您应该先在Github上创建一个问题。 可能不需要该功能，因此浪费在“拉取请求”上的时间很浪费。 您发现的错误实际上可能是您自己的代码中的错误，而不是库源代码中的错误。
Creating issues also helps avoid duplicative work done by other Open Sourcerers. Before creating a new issue, look through other open and closed issues to make sure it’s not already fixed.
创建问题还有助于避免其他开放源代码提供商进行重复的工作。 在创建新问题之前，请浏览其他未解决和已解决的问题，以确保尚未解决。
通过识字编程降低障碍 (Lowering barriers with literate programming)
It is valuable to lower the barrier to contribute to Open Source projects. There are a lot of intimidating factors when starting out on an Open Source project.
降低为开源项目做出贡献的障碍很有价值。 当开始一个开源项目时，有很多威胁因素。
What is the directory structure? What do I have to download to set up my environment? What base knowledge do I need to have to understand the program logic?
目录结构是什么？ 我必须下载什么才能设置我的环境？ 为了理解程序逻辑，我需要具备哪些基础知识？
A Code of Conduct is something that is becoming a staple in Open Source projects (see Facebook’s code of conduct as an example). I hope that annotated source code would become a staple as well on future projects.
行为准则已成为开源项目中的主要内容(请参阅Facebook的行为准则为例)。 我希望带注释的源代码也能在将来的项目中成为重要的内容。
What are your thoughts on Annotated Source Code? Is it something that you would like to see in more projects? Leave a comment below!
您对带注释的源代码有何看法？ 您是否希望在更多项目中看到它？ 在下面发表评论！
* Take a look at my annotated docco code.
*看看我带注释的docco代码 。
综合练习:qq练习