Pregledavao sam projekte otvorenog koda, pokušavajući pronaći sljedeći koji ću proučiti. Naišao sam underscorei njegov anotirani izvorni kod.
Obilježeni izvorni kod zapanjio me. Na desnoj strani stranice nalazio se izvorni kod. Na lijevoj strani stranice nalazile su se bilješke koje su objašnjavale svaki blok koda. To je bilo znanje koje ne bih stekao samostalnim čitanjem izvornog koda. Htio sam znati što je stvorilo ovu lijepu dokumentaciju i pronašao docco.
Što je docco?
doccoje "generator dokumentacije u stilu pismenog programiranja". To je program koji uzima vaš izvorni kôd i stvara bilješku s dokumentacijom.
Imajte na umu da doccosamo generira izgled dokumentacije. Komentari iz vašeg izvornog koda služe kao bilješke.
Kako koristiti docco?
Imam nevjerojatnu funkciju za koju želim stvoriti dokumentaciju. Uključio sam opisne komentare koji će biti moje bilješke.
Da doccobih ga koristio , instalirat ću ga lokalno sa npm install — save-dev docco.
doccoNaredba prihvaća imena datoteka, koji će generirati dokumentaciju. Moj program je spremljen kao app.js, pa ću ga pokrenuti ./node_modules/.bin/docco app.js.
I to je sve što je potrebno za stvaranje anotiranog izvornog koda!
Prema zadanim postavkama, doccosav će generirani dokument smjestiti u novi docs direktorij. Možete konfigurirati doccoupotrebu različitih CSS-a ili različitih izgleda. Pogledajte ovaj linearizgled označenog koda.
Pogledajte doccoREADME.md da biste vidjeli što još možete prilagoditi.
Počet ću koristiti doccoza početak bilježenja svih budućih projekata otvorenog koda kroz koje radim.
Što je pismeno programiranje?
Uz pismeno programiranje svoju programsku logiku želite izraziti jednostavnim jezikom. Osoba bi je trebala moći čitati poput knjige i razumjeti što se događa.
To znači da bi dokumentacija trebala slijediti isti redoslijed kao programska logika, a ne isti redoslijed kao izvorni kod. Programe pišemo redoslijedom koji čini našeg kompajlera sretnim. Taj redoslijed ponekad nije isto što i logika našeg programa.
Dakle, doccone generira pismenu programsku dokumentaciju u njenom pravom smislu. doccogenerira svoju dokumentaciju istim redoslijedom kao i izvorni kod. Ali, još uvijek mislim da je ovaj označeni izvorni kod dragocjen. Smatrajte to pseudokodom za svoj kôd.
Razdvajanje stvari i njihovo ponovno sastavljanje
Kad počinjete razumijevati novi projekt, uložite vrijeme u uspostavljanje povratne sprege. Možda postavlja testni paket, tako da možete urediti izvorni kod i vidjeti što se lomi. Možda pronalazi brzi način za pokretanje izvornog koda s vašeg terminala da bi vidio zapise konzole. Ne bih počeo pregledavati izvorni kod dok ne budete uspjeli stvoriti ovu petlju povratnih informacija.
To je ono što za mene čini Test Driven Development tako učinkovitim i ugodnim. Odmah vidite što vaš kôd radi. Bez povratne sprege kodirat ćete u mraku.
Pokrenuo sam doccoizvorni kod u svom terminalu pokretanjem node docco.js app.js, gdje app.jsje bila lažna datoteka. console.logPokretanjem ove naredbe uspio sam vidjeti rezultate svojih rezultata . Ovako je izgledao moj prekrasni izvorni kod, s preko 150 redaka vlastitih komentara.
Radite na projektima koje ćete redovito koristiti
Kent Dodds napisao je sjajan članak o doprinosu projektima otvorenog koda. Njegov je prijedlog da radite samo na projektima koje ćete redovito koristiti. Ovako sam odabrala projekte na kojima sam radila. Odlučio sam stvoriti vlastitu verziju doccojer bih to i sam želio koristiti.
Također sam se odlučio ne koristiti doccosamo jer se činilo da je njegovo održavanje mrtvo. Je li zadnji angažman od prije više od 2 godine? Postoje li neriješena neriješena pitanja od prije nekoliko godina? Postoji li puno zanemarenih zahtjeva za povlačenjem? To su dobri pokazatelji da ovaj projekt može biti mrtav ili neodržavan.
Što je najvažnije, želio sam stvoriti i objaviti docco-lite za iskustvo učenja.
Sjajne knjižnice postoje i izvan preglednika
Koncentrirao sam se na prednji svijet. Znam da ne postoje nedostaci knjižnica i okvira koji su mi dostupni. Nisam bio upućen u nevjerojatne knjižnice dostupne izvan front-end svijeta.
Evo nekoliko izvrsnih knjižnica koje su se doccokoristile.
1. fs-ekstra
fs-extraje poboljšana verzija modula datotečnog sustava (fs). Bilo je jako cool stvarati direktorije i datoteke, umjesto stvarati
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.
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.