Bevidst praksis: Hvad jeg lærte ved at læse docco

Jeg gennemsøgte open source-projekter og prøvede at finde den næste, jeg ville studere. Jeg kom over underscoreog dens kommenterede kildekode.

Den kommenterede kildekode forbløffede mig. På højre side af siden var kildekoden. På venstre side af siden var der noter, der forklarede hver blok kode. Dette var viden, som jeg ikke ville have fået ved at læse kildekoden på egen hånd. Jeg ville vide, hvad der producerede denne smukke dokumentation og fandt docco.

Hvad er docco?

doccoer en "literator-programmerings-stil dokumentationsgenerator." Det er et program, der tager din kildekode og opretter kommenteret dokumentation.

Bemærk, at der doccokun genereres dokumentationens layout. Kommentarerne fra din kildekode fungerer som kommentarerne.

Hvordan bruges docco?

Jeg har en fantastisk funktion, som jeg vil oprette dokumentation til. Jeg inkluderede beskrivende kommentarer, der fungerer som mine kommentarer.

For at bruge doccoinstallerer jeg det lokalt med npm install — save-dev docco.

Den doccoKommandoen accepterer filnavne, som det vil generere dokumentation for. Mit program er gemt som app.js, så jeg kører ./node_modules/.bin/docco app.js.

Og det er alt, hvad der kræves for at oprette kommenteret kildekode!

Placerer som standard doccoal genereret dokumentation i en ny docs mappe. Du kan konfigurere doccotil at bruge forskellige CSS eller forskellige layouts. Tjek dette linearlayout af den kommenterede kode.

Tjek docco's README.md for at se, hvad du ellers kan tilpasse.

Jeg begynder at bruge doccotil at kommentere alle fremtidige Open Source-projekter, som jeg arbejder igennem.

Hvad er literate programmering?

Med læsefærdig programmering vil du udtrykke din programlogik på almindeligt sprog. En person skal være i stand til at læse igennem den som en bog og forstå, hvad der sker.

Dette betyder, at dokumentation skal følge den samme rækkefølge som programlogikken og ikke den samme rækkefølge som kildekoden. Vi skriver programmer i en rækkefølge, der gør vores kompilator glad. Nogle gange er denne rækkefølge ikke den samme som logikken i vores program.

doccogenererer ikke læsefærdig programmeringsdokumentation i sin ægte forstand. doccogenererer sin dokumentation i samme rækkefølge som kildekoden. Men jeg tror stadig, at denne kommenterede kildekode er værdifuld. Tænk på det som pseudokode til din kode.

At tage ting fra hinanden og sætte dem sammen igen

Når du begynder at forstå et nyt projekt, skal du bruge tid på at oprette en feedback-loop. Det opsætter muligvis testpakken, så du kan redigere kildekoden og se, hvad der går i stykker. Det kan være at finde en hurtig måde at køre kildekoden fra din terminal for at se dine konsollogfiler. Jeg vil ikke begynde at gennemse kildekoden, før du har en måde at oprette denne feedback-loop på.

Dette er, hvad der gør Test Driven Development så effektiv og behagelig for mig. Du kan se, hvad din kode gør med det samme. Uden en feedback-loop vil du kode i mørket.

Jeg kørte doccokildekoden i min terminal ved at køre node docco.js app.js, hvor app.jsvar en dummy-fil. Jeg var i stand til at se resultaterne af mine console.logved at køre denne kommando. Sådan så min smukke kildekode ud med over 150 linjer med mine egne kommentarer.

Arbejd med projekter, du vil bruge regelmæssigt

Kent Dodds skrev en god artikel om bidrag til Open Source-projekter. Hans forslag er kun at arbejde på projekter, som du bruger regelmæssigt. Sådan har jeg valgt de projekter, jeg har arbejdet med. Jeg besluttede at oprette min egen version af, doccofordi det var noget, jeg selv ville bruge.

Jeg besluttede også imod at bruge doccosig selv, fordi vedligeholdelsen syntes at være død. Var den seneste forpligtelse for over 2 år siden? Er der uaktuelle udestående problemer fra år siden? Er der mange ignorerede Pull-anmodninger? Dette er gode indikatorer for, at dette projekt kan være dødt eller vedligeholdt.

Vigtigst af alt ville jeg oprette og udgive docco-lite til læringsoplevelsen.

Der findes også fantastiske biblioteker uden for browseren

Jeg har koncentreret mig om frontend-verdenen. Jeg ved, at der ikke er mangel på biblioteker og rammer, der er tilgængelige for mig. Jeg var uvidende om de fantastiske biblioteker, der var tilgængelige uden for front-end-verdenen.

Her er nogle fantastiske biblioteker, der doccobruges.

1. fs-ekstra

fs-extraer en forbedret version af filsystemmodulet (fs). Det var meget sejt at oprette mapper og filer i stedet for at oprette iv>’ s and

’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.