Намерна пракса: Оно што сам научио читајући докто

Прегледавао сам пројекте отвореног кода, покушавајући да нађем следећи који ћу проучити. underscoreНаишао сам и његов анотирани изворни код.

Обележени изворни код ме је запањио. На десној страни странице налазио се изворни код. На левој страни странице биле су белешке које су објашњавале сваки блок кода. То је било знање које не бих стекао самосталним читањем изворног кода. Желео сам да знам шта је створило ову лепу документацију и пронашао docco.

Шта је докко?

doccoје „генератор документације у стилу писменог програмирања“. То је програм који узима ваш изворни код и креира напомену са документацијом.

Имајте на уму да doccoсе генерише само распоред документације. Коментари из вашег изворног кода служе као напомене.

Како се користи доццо?

Имам невероватну функцију за коју желим да креирам документацију. Укључио сам описне коментаре који ће деловати као моје напомене.

Да бих је користио docco, инсталираћу је локално са npm install — save-dev docco.

doccoКоманда прихвата имена фајлова, који ће генерисати документацију за. Мој програм је сачуван као app.js, па ћу га покренути ./node_modules/.bin/docco app.js.

И то је све што је потребно за стварање анотираног изворног кода!

Подразумевано doccoће сву генерисану документацију сместити у нови docs директоријум. Можете да конфигуришете doccoупотребу различитих ЦСС-а или различитих распореда. Погледајте овај linearизглед означеног кода.

Погледајте doccoРЕАДМЕ.мд да бисте видели шта још можете да прилагодите.

Почећу да користим doccoкако бих започео бележење свих будућих пројеката отвореног кода кроз које радим.

Шта је писмено програмирање?

Уз писмено програмирање, своју програмску логику желите да изразите једноставним језиком. Човек би требало да буде у стању да је чита као књигу и разуме шта се дешава.

То значи да би документација требало да следи исти редослед као програмска логика, а не исти редослед као изворни код. Програме пишемо по редоследу који обрадује нашег компајлера. Овај редослед понекад није исто што и логика нашег програма.

Дакле, doccoне генерише писмену програмску документацију у њеном правом смислу. doccoгенерише своју документацију истим редоследом као и изворни код. Али, и даље мислим да је овај означени изворни код драгоцен. Замислите то као псеудокод за свој код.

Раздвајање ствари и њихово поновно састављање

Када почињете да разумете нови пројекат, уложите време у успостављање повратне спреге. Можда поставља тест пакет, тако да можете уредити изворни код и видети шта се ломи. Можда проналази брз начин за покретање изворног кода са вашег терминала да би се прегледали дневници конзоле. Не бих почео да прегледам изворни код док не будете имали начин да креирате ову петљу повратних информација.

То је оно што чини Тест Дривен Девелопмент тако ефикасним и пријатним за мене. Одмах видите шта ваш код ради. Без повратне спреге, кодираћете у мраку.

Покренуо сам doccoизворни код на свом терминалу покретањем node docco.js app.js, где app.jsје била лажна датотека. console.logПокретањем ове команде успео сам да видим резултате својих резултата . Овако је изгледао мој прелепи изворни код, са преко 150 редова мојих сопствених коментара.

Радите на пројектима које ћете редовно користити

Кент Доддс написао је сјајан чланак о доприносу пројектима отвореног кода. Његов предлог је да радите само на пројектима које ћете редовно користити. Овако сам одабрао пројекте на којима сам радио. Одлучио сам да креирам своју верзију doccoјер бих то и сам желео да користим.

Такође сам се одлучио да се не користим docco, јер је његово одржавање изгледало мртво. Да ли је последња обавеза од пре више од 2 године? Постоје ли застарела нерешена питања од пре неколико година? Да ли има пуно игнорисаних захтева за повлачење? То су добри показатељи да овај пројекат може бити мртав или неодржан.

Што је најважније, желео сам да створим и објавим доццо-лите за искуство учења.

Невероватне библиотеке постоје и изван прегледача

Концентрисао сам се на фронт-енд свет. Знам да не недостају библиотеке и оквири који су ми доступни. Нисам знао за невероватне библиотеке доступне изван света фронт-енд-а.

Ево неколико сјајних библиотека које су се doccoкористиле.

1. фс-екстра

fs-extraје побољшана верзија модула система датотека (фс). Било је врло кул креирати директоријуме и датотеке, уместо да их стварам 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.