الممارسة المتعمدة: ما تعلمته من قراءة دوكو

كنت أتصفح مشاريع مفتوحة المصدر ، محاولًا العثور على المشروع التالي الذي سأدرسه. لقد جئت underscoreوشيفرة المصدر المشروحة.

لقد أذهلتني شفرة المصدر المشروحة. على الجانب الأيمن من الصفحة كانت شفرة المصدر. على الجانب الأيسر من الصفحة كانت هناك ملاحظات تشرح كل كتلة من الكود. كانت هذه معرفة لم أكن لأحصل عليها من قراءة شفرة المصدر بمفردي. أردت أن أعرف ما الذي أنتج هذه الوثائق الجميلة ووجدتها docco.

ما هو دوكو؟

doccoهو "منشئ توثيق متعلم البرمجة بأسلوب". إنه برنامج يأخذ شفرة المصدر وينشئ وثائق مشروحة.

لاحظ أن هذا doccoفقط يولد تخطيط الوثائق. التعليقات من شفرة المصدر الخاصة بك بمثابة التعليقات التوضيحية.

كيفية استخدام دوكو؟

لدي وظيفة رائعة أريد إنشاء وثائق لها. لقد قمت بتضمين التعليقات الوصفية التي ستكون بمثابة تعليقاتي التوضيحية.

للاستخدام docco، سوف أقوم بتثبيته محليًا مع npm install — save-dev docco.

و doccoيقبل قيادة أسماء الملفات التي سوف تولد ثائق. تم حفظ برنامجي على هذا النحو app.js، لذا سأعمل ./node_modules/.bin/docco app.js.

وهذا كل ما يتطلبه الأمر لإنشاء شفرة مصدر مشروحة!

بشكل افتراضي ، doccoسيتم وضع جميع الوثائق التي تم إنشاؤها في docs دليل جديد . يمكنك التهيئة doccoلاستخدام CSS مختلف أو تخطيطات مختلفة. تحقق من linearتخطيط الكود المشروح هذا.

تحقق من doccoملف README.md لمعرفة الأشياء الأخرى التي يمكنك تخصيصها.

سأبدأ في استخدام doccoالتعليقات التوضيحية على جميع المشاريع مفتوحة المصدر المستقبلية التي أعمل من خلالها.

ما هي البرمجة المتعلمة؟

مع البرمجة المتعلمة ، تريد التعبير عن منطق البرنامج الخاص بك بلغة واضحة. يجب أن يكون الشخص قادرًا على قراءته مثل كتاب وفهم ما يحدث.

هذا يعني أن التوثيق يجب أن يتبع نفس ترتيب منطق البرنامج ، وليس نفس ترتيب التعليمات البرمجية المصدر. نكتب البرامج بترتيب يجعل المترجم لدينا سعيدًا. في بعض الأحيان ، لا يكون هذا الترتيب هو نفس منطق برنامجنا.

لذلك ، doccoلا تولد وثائق برمجة تعلم القراءة والكتابة بمعناها الحقيقي. doccoيولد وثائقه بنفس ترتيب كود المصدر الخاص به. لكن ، ما زلت أعتقد أن شفرة المصدر المشروحة هذه ذات قيمة. فكر في الأمر على أنه كود زائف لشفرتك.

تفكيك الأشياء وإعادة تجميعها معًا

عند البدء في فهم مشروع جديد ، استثمر الوقت في إعداد حلقة ملاحظات. قد يكون هو إعداد مجموعة الاختبار ، بحيث يمكنك تحرير التعليمات البرمجية المصدر ومعرفة ما يكسر. قد تجد طريقة سريعة لتشغيل الكود المصدري من جهازك الطرفي لرؤية سجلات وحدة التحكم الخاصة بك. لن أبدأ في تصفح الكود المصدري حتى يكون لديك طريقة لإنشاء حلقة الملاحظات هذه.

هذا ما يجعل التطوير المدفوع بالاختبار فعالًا وممتعًا جدًا بالنسبة لي. ترى ما تفعله التعليمات البرمجية الخاصة بك على الفور. بدون حلقة التغذية الراجعة ، سوف تقوم بالترميز في الظلام.

كنت أقوم بتشغيل doccoشفرة المصدر في الجهاز الطرفي عن طريق التشغيل node docco.js app.js، حيث app.jsكان ملفًا وهميًا. تمكنت من رؤية نتائج بلدي من console.logخلال تشغيل هذا الأمر. هذا ما بدت عليه شفرة المصدر الجميلة ، مع أكثر من 150 سطرًا من تعليقاتي الخاصة.

العمل في المشاريع التي سوف تستخدمها بانتظام

كتب Kent Dodds مقالة رائعة حول المساهمة في مشاريع مفتوحة المصدر. اقتراحه هو العمل فقط على المشاريع التي ستستخدمها بانتظام. هذه هي الطريقة التي اخترت بها المشاريع التي عملت عليها. قررت إنشاء نسختي الخاصة من doccoلأنها كانت شيئًا أرغب في استخدامه بنفسي.

قررت أيضًا عدم استخدام doccoنفسها لأن صيانتها بدت وكأنها ميتة. هل كان آخر التزام منذ أكثر من عامين؟ هل هناك قضايا معلقة قديمة منذ سنوات؟ هل هناك الكثير من طلبات السحب التي تم تجاهلها؟ هذه مؤشرات جيدة على أن هذا المشروع قد مات أو لم تتم صيانته.

الأهم من ذلك ، كنت أرغب في إنشاء ونشر docco-lite لتجربة التعلم.

توجد مكتبات رائعة خارج المتصفح أيضًا

لقد ركزت على عالم الواجهة الأمامية. أعلم أنه لا يوجد نقص في المكتبات والأطر المتاحة لي. كنت أجهل المكتبات الرائعة المتاحة خارج عالم الواجهة الأمامية.

فيما يلي بعض المكتبات الرائعة التي تم doccoاستخدامها.

1. FS- اضافية

fs-extraهو نسخة معززة من وحدة نظام الملفات (fs). كان من الرائع إنشاء أدلة وملفات بدلاً من إنشاء ملفات 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.