Latihan yang Disengaja: Apa yang saya pelajari dari membaca docco

Saya melihat-lihat proyek open source, mencoba menemukan proyek berikutnya yang akan saya pelajari. Saya menemukan underscoredan kode sumbernya yang beranotasi.

Kode sumber beranotasi membuat saya takjub. Di sisi kanan halaman adalah kode sumber. Di sisi kiri halaman ada catatan yang menjelaskan setiap blok kode. Ini adalah pengetahuan yang tidak akan saya peroleh dari membaca kode sumber saya sendiri. Saya ingin tahu apa yang menghasilkan dokumentasi indah ini dan menemukan docco.

Apa itu docco?

doccoadalah "generator dokumentasi gaya pemrograman terpelajar". Ini adalah program yang mengambil kode sumber Anda dan membuat dokumentasi beranotasi.

Perhatikan bahwa doccohanya menghasilkan tata letak dokumentasi. Komentar dari kode sumber Anda berfungsi sebagai penjelasan.

Bagaimana cara menggunakan docco?

Saya memiliki fungsi luar biasa yang ingin saya buat dokumentasinya. Saya menyertakan komentar deskriptif yang akan bertindak sebagai anotasi saya.

Untuk menggunakan docco, saya akan menginstalnya secara lokal dengan npm install — save-dev docco.

The doccoperintah menerima nama file, yang akan menghasilkan dokumentasi untuk. Program saya disimpan sebagai app.js, jadi saya akan menjalankan ./node_modules/.bin/docco app.js.

Dan hanya itu yang diperlukan untuk membuat kode sumber beranotasi!

Secara default, doccoakan menempatkan semua dokumentasi yang dihasilkan ke dalam docs direktori baru . Anda dapat mengonfigurasi doccountuk menggunakan CSS yang berbeda atau tata letak yang berbeda. Lihat lineartata letak kode beranotasi ini.

Lihat doccoREADME.md untuk melihat apa lagi yang dapat Anda sesuaikan.

Saya akan mulai menggunakan doccountuk mulai membuat anotasi semua proyek Open Source masa depan yang saya kerjakan.

Apa itu pemrograman melek huruf?

Dengan pemrograman terpelajar, Anda ingin mengekspresikan logika program Anda dalam bahasa sederhana. Seseorang harus dapat membacanya seperti buku dan memahami apa yang terjadi.

Ini berarti bahwa dokumentasi harus mengikuti urutan yang sama dengan logika program, dan bukan urutan yang sama seperti kode sumber. Kami menulis program dalam urutan yang membuat kompiler kami senang. Terkadang, urutan ini tidak sama dengan logika program kita.

Jadi, doccotidak menghasilkan dokumentasi pemrograman yang melek huruf dalam arti sebenarnya. doccomenghasilkan dokumentasinya dalam urutan yang sama seperti kode sumbernya. Tapi, saya masih berpikir bahwa kode sumber beranotasi ini berharga. Anggap saja sebagai pseudocode untuk kode Anda.

Membongkar dan menyatukannya kembali

Saat mulai memahami proyek baru, investasikan waktu untuk menyiapkan umpan balik. Ini mungkin sedang menyiapkan paket pengujian, sehingga Anda dapat mengedit kode sumber dan melihat apa yang rusak. Mungkin menemukan cara cepat untuk menjalankan kode sumber dari terminal Anda untuk melihat log konsol Anda. Saya tidak akan mulai menjelajahi kode sumber sampai Anda memiliki cara untuk membuat putaran umpan balik ini.

Inilah yang membuat Test Driven Development begitu efektif dan menyenangkan bagi saya. Anda melihat apa yang dilakukan kode Anda secara instan. Tanpa umpan balik, Anda akan membuat kode dalam kegelapan.

Saya menjalankan doccokode sumber di terminal saya dengan menjalankan node docco.js app.js, di mana app.jsfile dummy. Saya bisa melihat hasil saya console.logdengan menjalankan perintah ini. Seperti inilah tampilan kode sumber saya yang indah, dengan lebih dari 150 baris komentar saya sendiri.

Kerjakan proyek yang akan Anda gunakan secara teratur

Kent Dodds menulis artikel bagus tentang berkontribusi pada proyek Open Source. Sarannya hanya mengerjakan proyek yang akan Anda gunakan secara teratur. Beginilah cara saya memilih proyek yang telah saya kerjakan. Saya memutuskan untuk membuat versi saya sendiri doccokarena itu adalah sesuatu yang ingin saya gunakan sendiri.

Saya juga memutuskan untuk tidak menggunakan doccosendiri karena perawatannya sepertinya sudah mati. Apakah komitmen terbaru lebih dari 2 tahun yang lalu? Apakah ada masalah luar biasa yang sudah basi dari tahun lalu? Apakah ada banyak Permintaan Tarik yang diabaikan? Ini adalah indikator bagus bahwa proyek ini mungkin mati atau tidak terawat.

Yang terpenting, saya ingin membuat dan menerbitkan docco-lite untuk pengalaman belajar.

Pustaka yang mengagumkan juga ada di luar browser

Saya telah berkonsentrasi pada dunia front-end. Saya tahu tidak ada kekurangan perpustakaan dan kerangka kerja yang tersedia untuk saya. Saya tidak peduli dengan perpustakaan luar biasa yang tersedia di luar dunia front-end.

Berikut adalah beberapa perpustakaan luar biasa yang doccodigunakan.

1. fs-ekstra

fs-extraadalah versi modul file system (fs) yang ditingkatkan. Sangat keren membuat direktori dan file, daripada membuativ>’s 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.