Szándékos gyakorlat: Amit a docco olvasásából tanultam

Nyílt forráskódú projekteket böngésztem, és megpróbáltam megtalálni a következőt, amelyet tanulmányozni fogok. Rátaláltam underscoreés annak jegyzetelt forráskódjára.

A megjegyzéssel ellátott forráskód meghökkent. Az oldal jobb oldalán a forráskód volt. Az oldal bal oldalán az egyes kódblokkok magyarázata található. Ez olyan tudás volt, amelyet nem szereztem volna meg, ha egyedül olvasom el a forráskódot. Tudni akartam, mi hozta létre és találta meg ezt a gyönyörű dokumentációt docco.

Mi a docco?

doccoegy „írástudó programozási stílusú dokumentációs generátor”. Ez egy olyan program, amely megkapja a forráskódot és jegyzetekkel ellátott dokumentációt készít.

Vegye figyelembe, hogy doccocsak a dokumentáció elrendezését generálja. A forráskód megjegyzései kommentárként szolgálnak.

Hogyan kell használni a docco-t?

Van egy csodálatos funkcióm, amelyhez dokumentációt szeretnék készíteni. Vettem leíró megjegyzéseket, amelyek kommentárként működnek.

Ahhoz, hogy használni doccofogom telepíteni helyben npm install — save-dev docco.

A doccoparancs elfogadja a fájlneveket, amelyekhez dokumentációt generál. A programom a rendszer mentve app.js, így futni fogok ./node_modules/.bin/docco app.js.

És ennyi kell a kommentált forráskód létrehozásához!

Alapértelmezés szerint az doccoösszes létrehozott dokumentációt egy új docs könyvtárba helyezi . Beállíthatja doccokülönböző CSS vagy különböző elrendezések használatát. Nézze meg lineara kommentált kód ezen elrendezését.

Nézze meg a doccoREADME.md fájlt, hogy megnézze, mit lehet még testreszabni.

Kezdem használni doccoaz összes jövőbeli nyílt forráskódú projekt jegyzetelését, amelyeken keresztül dolgozom.

Mi az írástudás programozása?

Az írástudó programozással egyszerű nyelven szeretné kifejezni a programlogikáját. Az embernek képesnek kell lennie arra, hogy átolvassa azt, mint egy könyvet, és megértse, mi történik.

Ez azt jelenti, hogy a dokumentációnak ugyanabban a sorrendben kell lennie, mint a program logikájának, és nem azonosnak kell lennie a forráskóddal. Olyan sorrendben írunk programokat, amelyek örömet okoznak fordítónknak. Néha ez a sorrend nem azonos a program logikájával.

Tehát docconem generálja az írástudó programozási dokumentációt a legigazibb értelmében. doccoa forráskódjával megegyező sorrendben generálja dokumentációját. De továbbra is úgy gondolom, hogy ez a feljegyzett forráskód értékes. Gondoljon arra, hogy a kódja álkódja.

Szétszedni és újra összerakni a dolgokat

Amikor elkezd egy új projektet megérteni, fordítson időt egy visszacsatolási hurok létrehozására. Lehet, hogy a tesztcsomagot állítja be, így szerkesztheti a forráskódot és megnézheti, hogy mi szakad meg. Lehet, hogy talál egy gyors módszert a forráskód futtatására a terminálról a konzolnaplók megtekintéséhez. Addig nem kezdeném böngészni a forráskódot, amíg nincs módja létrehozni ezt a visszacsatolási ciklust.

Ez teszi számomra a tesztvezérelt fejlesztést olyan hatékonnyá és élvezetessé. Azonnal látja, mit csinál a kódja. Visszacsatolási hurok nélkül sötétben fog kódolni.

Futottam doccoforráskódja én terminálon fut node docco.js app.js, ahol app.jsvolt egy dummy fájl. A console.logparancs futtatásával láthattam az eredményeim eredményeit . Így nézett ki a gyönyörű forráskódom, több mint 150 sor saját megjegyzéssel.

Dolgozzon olyan projekteken, amelyeket rendszeresen használ

Kent Dodds nagyszerű cikket írt az Open Source projektekhez való hozzájárulásról. Javaslata, hogy csak olyan projekteken dolgozzon, amelyeket rendszeresen használ. Így választottam azokat a projekteket, amelyeken dolgoztam. Úgy döntöttem, hogy elkészítem a saját verziómat, doccomert ezt magam is szeretném használni.

Úgy döntöttem, hogy nem használom doccoönmagát, mert a karbantartása halottnak tűnt. Több mint 2 évvel ezelőtti legutóbbi elkötelezettség volt? Vannak-e elavult, évekkel ezelőtti kérdések? Sok figyelmen kívül hagyott lehívási kérelem van? Ezek jó mutatók arra nézve, hogy ez a projekt halott vagy nem karbantartott.

Ami a legfontosabb: szerettem volna létrehozni és közzétenni docco-lite-t a tanulási élmény érdekében.

Félelmetes könyvtárak léteznek a böngészőn kívül is

A front-end világra koncentráltam. Tudom, hogy nincs hiány könyvtárakból és keretrendszerekből, amelyek elérhetőek számomra. Tudatlan voltam a front-end világon kívül elérhető csodálatos könyvtárakról.

Íme néhány fantasztikus könyvtár, amelyet doccohasznált.

1. fs-extra

fs-extraa fájlrendszer (fs) modul kibővített verziója. Nagyon jó volt könyvtárakat és fájlokat létrehozni ahelyett, hogy létrehoznánk 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.