Автор оригинала: FreeCodeCamp Community Member.
Энтони Нг
Я просматривал проекты с открытым исходным кодом, пытаясь найти следующий, который я бы учился. Я пришел на подчеркивание и его Аннотированный исходный код Отказ
Аннотированный исходный код поразил меня. На правой стороне страницы был исходный код. На левой стороне страницы были примечания, объясняющие каждый блок кода. Это было знание, что я бы не получил от чтения исходного кода самостоятельно. Я хотел знать, что произвело эту прекрасную документацию и найден DOCCO Отказ
Что такое DOCCO?
DOCCO является «генератором документации по грамотно-программированию в стиле программирования. ” Это программа, которая принимает ваш исходный код и создает аннотированную документацию.
Обратите внимание, что DOCCO только генерирует макет документации. Комментарии вашего исходного кода служат аннотациями.
Как использовать DOCCO?
У меня есть удивительная функция, которую я хочу создать документацию. Я включил описательные комментарии, которые будут действовать как мои аннотации.
Использовать DOCCO Я установлю его локально с NPM Install - Save-dev DOCCO Отказ
DOCCO Команда принимает имена файлов, которые он будет генерировать документацию для. Моя программа сохраняется как app.js Так что я бегу ./node_modules/.bin/docco app.js Отказ
И это все, что нужно для создания Аннотированный исходный код Действительно
По умолчанию DOCCO Поместите всю созданную документацию в новый Документы каталог. Вы можете настроить DOCCO использовать разные CSS или разные макеты. Проверьте это линейный Макет аннотированного кода Отказ
Проверьте DOCCO ‘s Readme.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 Является ли BEEFEED UP-версия модуля файловой системы (FS). Было очень круто, чтобы создавать каталоги и файлы, а не создавать S a D
2. командир
командир это библиотека, которая создает интерфейсы командной строки.
3. мелочи
Мел Позволяет стимулировать ваши терминальные струны?
4. highlightjs.
Highlightjs Можно создать HTML из строки кода. С помощью этого HTML-выходов вы можете добавить CSS для стиля ваших фрагментов кода.
Шаблоны JavaScript
В общей сборке Bootcamp я выучил руль перед модным угловым/реакцией. Ручки – это простой язык шаблона шаблона JavaScript, который помещает JavaScript в ваш HTML. Если у вас есть простой проект, иногда простой язык шаблонов, чтобы получить вас. Накладные расходы на реакцию не имеют смысла.
Я работал с реагированием на прошлый год. Простота и мощность использования шаблонов JavaScript удивило меня. подчеркивание Библиотека предоставляет простой способ использования шаблона JavaScript.
Если вы хотите включить JavaScript в вашем шаблоне, используйте <% %>.
Если вы хотите JavaScript сделать как текст, используйте <% = %> (обратите внимание на равный (=) знак).
Вы даже можете получить причудливые и использовать для петлей с помощью шаблонов JavaScript.
Теперь давайте поставим все вместе, используя подчеркивание ‘s Шаблон метод.
Нам не нужен WebPack, Babel, или виртуальный дом. Хорошие дни олаи построения веб-страницы?
Создайте ценные PRS.
Вклад в проект с открытым исходным кодом должен обеспечить ценность для кого-то. Вы можете помочь другим, исправляя ошибки, добавляя функции или обновляющую документацию. Вы можете помочь себе, работая над проектом, где вы узнаете что-то новое.
Но убедитесь, что работа, которую вы делаете, не потрачена впустую.
Посмотрите на УМД репозиторий Отказ
Мы можем увидеть некоторые проблемы форматирования отметки в Readme.md. Это было бы идеальной возможностью создать запрос на тягу, чтобы исправить это.
Но прежде чем мы сделаем это, давайте проверим, что наши усилия не потрачены впустую. Давайте проверим выдающиеся запросы на тягу.
Обратите внимание, как есть 11 выдающихся запросов на тягу, которые фиксируют то же самое.
Это круто, что люди достаточно заботятся об этом проекте, чтобы исправить его документацию. Но создание 12-го запроса на тягу, чтобы исправить readme.md, никому не поможет.
То же самое можно сказать, прежде чем создать запрос на тягу, чтобы добавить новую функцию или исправить ошибку. Вы должны сначала создать проблему на GitHub. Функция может быть не хотела, поэтому время, потраченное на запрос на тягу, – это отходы. Облег, которую вы нашли, может быть, может быть ошибкой в вашем собственном коде, а не ошибка в исходном коде библиотеки.
Создание вопросов также помогает избежать дублирующей работы, выполненной другими открытыми хищниками. Перед созданием нового вопроса просмотрите другие открытые и закрытые проблемы, чтобы убедиться, что он еще не исправлен.
Опускание барьеров с грамотным программированием
Ценно снизить барьер, чтобы способствовать проектам с открытым исходным кодом. При запуске на проекте открытого исходного происхождения много запугивающих факторов.
Что такое структура каталога? Что мне нужно скачать, чтобы настроить мою среду? Какие базовые знания мне нужно, чтобы понять логику программы?
Кодекс поведения – это то, что становится скотным в проектах с открытым исходным кодом (см. Код поведения Facebook в качестве примера). Я надеюсь, что аннотированный исходный код стал бы скоплением, а также на будущих проектах.
Каковы ваши мысли о аннотированном исходном коде? Это то, что вы хотели бы видеть в большем количестве проектов? Оставьте комментарий ниже!
* Посмотрите на мой Аннотированный код DOCCO Отказ
Оригинал: “https://www.freecodecamp.org/news/deliberate-practice-what-i-learned-from-reading-docco-7884b5979c6c/”