Навмисна практика: те, чого я навчився читаючи докко

Я переглядав проекти з відкритим кодом, намагаючись знайти наступний, який я буду вивчати. Я натрапив на underscoreйого анотований вихідний код.

Анотований вихідний код мене вразив. Праворуч на сторінці знаходився вихідний код. У лівій частині сторінки були примітки, що пояснювали кожен блок коду. Це було знання, якого я б не отримав від самостійного читання вихідного коду. Я хотів знати, що створило цю чудову документацію і знайшов docco.

Що таке docco?

doccoє "генератором документації в стилі грамотного програмування". Це програма, яка бере ваш вихідний код і створює анотовану документацію.

Зверніть увагу, що doccoгенерується лише макет документації. Коментарі з вихідного коду служать анотаціями.

Як користуватися docco?

У мене є дивовижна функція, для якої я хочу створити документацію. Я включив описові коментарі, які будуть виконувати роль моїх анотацій.

Для використання doccoя встановлю його локально за допомогою npm install — save-dev docco.

doccoКоманда приймає імена файлів, які він буде генерувати документацію для. Моя програма збережена як app.js, тому я запуститиму ./node_modules/.bin/docco app.js.

І це все, що потрібно для створення анотованого вихідного коду!

За замовчуванням doccoвся генерована документація буде розміщена в новому docs каталозі. Ви можете налаштувати doccoвикористання різних CSS або різних макетів. Ознайомтесь із цим linearмакетом коду з кодами.

Перевірте doccoREADME.md, щоб побачити, що ще ви можете налаштувати.

Я збираюся почати використовувати, doccoщоб почати анотувати всі майбутні проекти з відкритим кодом, які я працюю.

Що таке грамотне програмування?

За допомогою грамотного програмування ви хочете висловити логіку програми простою мовою. Людина повинна мати можливість читати це як книгу і розуміти, що відбувається.

Це означає, що документація повинна виконувати той самий порядок, що і логіка програми, а не той самий порядок, що і вихідний код. Ми пишемо програми в порядку, який робить наш компілятор щасливим. Іноді цей порядок не такий, як логіка нашої програми.

Отже, doccoне генерує грамотної документації з програмування в її прямому розумінні. doccoгенерує свою документацію в тому ж порядку, що і вихідний код. Але, я все ще вважаю, що цей анотований вихідний код цінний. Подумайте про це як про псевдокод для вашого коду.

Розбираючи речі і складаючи їх назад

Починаючи розуміти новий проект, вкладіть час у створення циклу зворотного зв'язку. Можливо, це налаштування тестового набору, щоб ви могли редагувати вихідний код і бачити, що зламалося. Можливо, він знаходить швидкий спосіб запустити вихідний код із терміналу, щоб переглянути журнали консолі. Я б не почав переглядати вихідний код, поки у вас не буде способу створити цей цикл зворотного зв'язку.

Це те, що робить розробку, керовану випробуваннями, такою ефективною та приємною для мене. Ви бачите, що ваш код робить миттєво. Без петлі зворотного зв'язку ви будете кодувати в темряві.

Я запускав doccoвихідний код у своєму терміналі, запустивши node docco.js app.js, де app.jsбув фіктивний файл. Я зміг побачити результати своєї console.logроботи, запустивши цю команду. Так виглядав мій чудовий вихідний код із понад 150 рядками моїх власних коментарів.

Працюйте над проектами, якими будете користуватися регулярно

Кент Доддс написав чудову статтю про участь у проектах з відкритим кодом. Він пропонує лише працювати над проектами, якими ви будете користуватися регулярно. Ось так я обрав проекти, над якими працював. Я вирішив створити власну версію, doccoтому що це те, чим я хотів би скористатися сам.

Я також вирішив не використовувати doccoсебе, оскільки його обслуговування здавалося мертвим. Чи була остання комісія понад 2 роки тому? Чи є застарілі невирішені проблеми років тому? Чи багато ігнорованих запитів на витягування? Це хороші показники того, що цей проект може бути мертвим або не підтримуватися.

Найголовніше, я хотів створити та опублікувати docco-lite для досвіду навчання.

Чудові бібліотеки існують і за межами браузера

Я зосередився на зовнішньому світі. Я знаю, що бібліотек та фреймворків, які мені доступні, не бракує. Я не знав про дивовижні бібліотеки, доступні за межами зовнішнього світу.

Ось декілька чудових бібліотек, які doccoвикористовувались.

1. fs-extra

fs-extra- це вдосконалена версія модуля файлової системи (fs). Було дуже класно створювати каталоги та файли замість того, щоб створюватиiv>’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.