Estaba navegando por proyectos de código abierto, tratando de encontrar el próximo que estudiaría. Me encontré con underscoresu código fuente anotado.
El código fuente anotado me sorprendió. En el lado derecho de la página estaba el código fuente. En el lado izquierdo de la página había notas que explican cada bloque de código. Este fue un conocimiento que no habría obtenido leyendo el código fuente por mi cuenta. Quería saber qué produjo y encontré esta hermosa documentación docco.
¿Qué es docco?
doccoes un "generador de documentación con estilo de programación alfabetizada". Es un programa que toma su código fuente y crea documentación anotada.
Tenga en cuenta que doccosolo genera el diseño de la documentación. Los comentarios de su código fuente sirven como anotaciones.
¿Cómo usar docco?
Tengo una función asombrosa para la que quiero crear documentación. Incluí comentarios descriptivos que actuarán como mis anotaciones.
Para usarlo docco, lo instalaré localmente con npm install — save-dev docco.
El doccocomando acepta nombres de archivos, para los cuales generará documentación. Mi programa se guarda como app.js, así que lo ejecutaré ./node_modules/.bin/docco app.js.
¡Y eso es todo lo que se necesita para crear un código fuente anotado!
De forma predeterminada, doccocolocará toda la documentación generada en un nuevo docs directorio. Puede configurar doccopara usar diferentes CSS o diferentes diseños. Vea este lineardiseño del código anotado.
Consulte doccoel archivo README.md para ver qué más puede personalizar.
Voy a comenzar a usar doccopara comenzar a anotar todos los proyectos de código abierto futuros en los que trabajo.
¿Qué es la programación alfabetizada?
Con la programación alfabetizada, desea expresar la lógica de su programa en lenguaje sencillo. Una persona debería poder leerlo como un libro y comprender lo que está sucediendo.
Esto significa que la documentación debe seguir el mismo orden que la lógica del programa y no el mismo orden que el código fuente. Escribimos programas en un orden que hace feliz a nuestro compilador. A veces, este orden no es el mismo que la lógica de nuestro programa.
Por lo tanto, doccono genera documentación de programación alfabetizada en su verdadero sentido. doccogenera su documentación en el mismo orden que su código fuente. Pero sigo pensando que este código fuente anotado es valioso. Piense en ello como un pseudocódigo para su código.
Desarmar cosas y volver a armarlas
Cuando empiece a comprender un nuevo proyecto, invierta tiempo en establecer un circuito de retroalimentación. Puede que esté configurando el conjunto de pruebas, para que pueda editar el código fuente y ver qué se rompe. Puede encontrar una forma rápida de ejecutar el código fuente desde su terminal para ver los registros de su consola. No comenzaría a navegar por el código fuente hasta que tenga una forma de crear este ciclo de retroalimentación.
Esto es lo que hace que el desarrollo basado en pruebas sea tan eficaz y agradable para mí. Ves lo que hace tu código al instante. Sin un circuito de retroalimentación, estará codificando en la oscuridad.
Estaba ejecutando doccoel código fuente de mi terminal ejecutando node docco.js app.js, donde app.jsestaba un archivo ficticio. Pude ver los resultados de mi console.logejecutando este comando. Así es como se veía mi hermoso código fuente, con más de 150 líneas de mis propios comentarios.
Trabaja en proyectos que usarás regularmente
Kent Dodds escribió un gran artículo sobre cómo contribuir a proyectos de código abierto. Su sugerencia es trabajar solo en proyectos que usará regularmente. Así es como he elegido los proyectos en los que he trabajado. Decidí crear mi propia versión doccoporque era algo que me gustaría usar yo mismo.
También decidí no usarlo doccoporque su mantenimiento parecía estar muerto. ¿Fue la última confirmación de hace más de 2 años? ¿Hay asuntos obsoletos pendientes de hace años? ¿Hay muchas solicitudes de extracción ignoradas? Estos son buenos indicadores de que este proyecto puede estar muerto o sin mantenimiento.
Lo más importante es que quería crear y publicar docco-lite para la experiencia de aprendizaje.
También existen fantásticas bibliotecas fuera del navegador
Me he concentrado en el mundo del front-end. Sé que no hay escasez de bibliotecas y marcos que estén disponibles para mí. No conocía las increíbles bibliotecas disponibles fuera del mundo del front-end.
Aquí hay algunas bibliotecas increíbles que doccousaron.
1. fs-extra
fs-extraes una versión reforzada del módulo del sistema de archivos (fs). Fue genial crear directorios y archivos, en lugar de crears and
Original text
’s.2. commander
commander is a library that creates command-line interfaces.
3. chalk
chalk lets you style your terminal strings ?
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.
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.
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.
If you want to include JavaScript in your template, use <% %>.
If you want the JavaScript to render as text, use <%= %> (note the equal (=) sign).
You can even get fancy and use for-loops with JavaScript templates.
Now let’s put it all together using underscore's template method.
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.
2. commander
commander is a library that creates command-line interfaces.
3. chalk
chalk lets you style your terminal strings ?
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.
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.
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.
If you want to include JavaScript in your template, use <% %>.
If you want the JavaScript to render as text, use <%= %> (note the equal (=) sign).
You can even get fancy and use for-loops with JavaScript templates.
Now let’s put it all together using underscore's template method.
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.