by Anthony Ng
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.
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
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 only generates the layout of the documentation. The comments from your source code serves as the annotations.
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.
docco, I will install it locally with
npm install — save-dev docco.
docco command accepts file names, which it will generate documentation for. My program is saved as
app.js, so I will run
And that’s all it takes to create annotated source code!
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’s README.md to see what else you can customize.
I am going to start using
docco to start annotating all future Open Source projects that I work through.
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.
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.
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.
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.
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.
Most importantly, I wanted to create and publish docco-lite for the learning experience.
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
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
s and <h1>’s.
commander is a library that creates command-line interfaces.
chalk lets you style your terminal strings ?
highlightjs can create HTML out of a string of code. With this HTML output, you can add CSS to style your code snippets.
<%= %> (note the equal (=) sign).
Now let’s put it all together using
We didn’t need webpack, Babel, or the virtual DOM. The good ol’ days of building a webpage ?.
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.
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.
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.
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.
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.
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.
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.