Tarkoitettu käytäntö: Mitä opin oppimalla doccoa

Selasin avoimen lähdekoodin projekteja yrittäen löytää seuraavan tutkittavani. Tulin underscoreja sen kommentoitu lähdekoodi.

Merkitty lähdekoodi hämmästytti minua. Sivun oikealla puolella oli lähdekoodi. Sivun vasemmalla puolella oli muistiinpanoja, joissa selitettiin jokainen koodilohko. Tämä oli tieto, jota en olisi saanut lukemalla lähdekoodia yksin. Halusin tietää, mikä tuotti tämän kauniin dokumentaation ja löysi docco.

Mikä on docco?

doccoon "lukutaito-ohjelmointityylinen dokumentointigeneraattori". Se on ohjelma, joka ottaa lähdekoodisi ja luo huomautetut asiakirjat.

Huomaa, että doccose luo vain dokumentaation asettelun. Lähdekoodisi kommentit toimivat merkinnöinä.

Kuinka käyttää doccoa?

Minulla on hämmästyttävä toiminto, jolle haluan luoda dokumentaation. Lisäsin kuvaavia kommentteja, jotka toimivat merkintöinä.

Käyttöä varten doccoasennan sen paikallisesti npm install — save-dev docco.

doccoKomento hyväksyy tiedostojen nimet, jotka se tuottaa dokumentaatiota. Ohjelmani on tallennettu nimellä app.js, joten aion suorittaa ./node_modules/.bin/docco app.js.

Ja siinä kaikki mitä tarvitset kommentoitujen lähdekoodien luomiseen!

Oletusarvoisesti doccokaikki luotu dokumentaatio sijoitetaan uuteen docs hakemistoon. Voit määrittää doccokäyttämään eri CSS: ää tai eri asetteluja. Tarkista tämä linearkommentoidun koodin asettelu.

Katso doccoREADME.md: stä, mitä muuta voit muokata.

Aion alkaa käyttää doccomerkintöjä kaikille tuleville avoimen lähdekoodin projekteille, joita työskentelen läpi.

Mikä on lukutaito-ohjelmointi?

Lukutaito-ohjelmoinnilla haluat ilmaista ohjelmalogiikkasi selkeällä kielellä. Henkilön tulisi pystyä lukemaan se läpi kirjan tavoin ja ymmärtämään mitä tapahtuu.

Tämä tarkoittaa, että dokumentaation tulisi noudattaa samaa järjestystä kuin ohjelmalogiikka, eikä samaa järjestystä kuin lähdekoodi. Kirjoitamme ohjelmia järjestyksessä, joka tekee kääntäjämme onnelliseksi. Joskus tämä järjestys ei ole sama kuin ohjelmamme logiikka.

Joten, doccoei luo lukutaitoista ohjelmointidokumentaatiota sen todellisessa mielessä. doccoluo dokumentaationsa samassa järjestyksessä kuin lähdekoodinsa. Mutta uskon silti, että tämä kommentoitu lähdekoodi on arvokas. Ajattele sitä koodisi pseudokoodina.

Hajota asiat ja laita ne takaisin yhteen

Kun alat ymmärtää uutta projektia, sijoita aika palautesilmukan luomiseen. Se saattaa olla asettamassa testipakettia, jotta voit muokata lähdekoodia ja nähdä, mitkä rikkoutuvat. Se voi olla nopea tapa suorittaa lähdekoodi terminaalista nähdäksesi konsolilokisi. En alkaisi selata lähdekoodia, ennen kuin sinulla on tapa luoda tämä palautesilmukka.

Tämä tekee testikäyttöisen kehityksen minulle niin tehokasta ja nautittavaa. Näet mitä koodisi tekee heti. Ilman palautesilmukkaa koodaat pimeässä.

Juoksin doccolähdekoodia päätelaitteessani juoksemalla node docco.js app.js, missä app.jsoli nuken tiedosto. Pystyin näkemään tulosteni tulokset console.logsuorittamalla tämän komennon. Tältä näytti kaunis lähdekoodini, jossa oli yli 150 riviä omia kommenttejani.

Työskentele säännöllisesti käyttämiesi projektien parissa

Kent Dodds kirjoitti suuren artikkelin osallistumisesta avoimen lähdekoodin projekteihin. Hänen ehdotuksensa on työskennellä vain sellaisten projektien parissa, joita käytät säännöllisesti. Näin olen valinnut projektit, joissa olen työskennellyt. Päätin luoda oman versioni, doccokoska haluaisin käyttää sitä itse.

Päätin myös olla käyttämättä doccoitseään, koska sen ylläpito näytti olevan kuollut. Oliko viimeisin sitoumus yli 2 vuotta sitten? Onko vanhentuneita ratkaisemattomia asioita vuosia sitten? Onko ohitettuja vetopyyntöjä paljon? Nämä ovat hyviä indikaattoreita siitä, että tämä projekti voi olla kuollut tai ylläpitämätön.

Mikä tärkeintä, halusin luoda ja julkaista docco-lite-oppimiskokemusta varten.

Mahtavia kirjastoja on myös selaimen ulkopuolella

Olen keskittynyt etupään maailmaan. Tiedän, että käytettävissä olevista kirjastoista ja kehyksistä ei ole pulaa. Olin tietämätön hämmästyttävistä kirjastoista, joita oli saatavana käyttöliittymän ulkopuolella.

Tässä on joitain mahtavia kirjastoja, joita doccokäytettiin.

1. fs-ylimääräinen

fs-extraon tiedostojärjestelmän (fs) moduulin parannettu versio. Oli erittäin hienoa luoda hakemistoja ja tiedostoja luomisen sijaan 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.