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

دعونا نلقي نظرة على بعض المبادئ الهامة لإنشاء رمز التوثيق الذاتي.

لا تستخدم "الأرقام السحرية"

قل لي ، ماذا يعني هذا الخط؟

if (students.length > 23) { 

يتحقق إذا كان هناك طلاب أكثر من 23؟ وماذا يعني ذلك؟ لماذا بالضبط 23 ، وليس ، ويقول ، 24؟

الرقم السحري هو رقم بدون سياق. سوف تحتاج إلى قضاء بعض الوقت والجهد لفهم هذا السياق. تخلص من العمل غير الضروري ، وإعطاء الرقم على الفور صراحة:

 const maxClassSize = 23; if (students.length > maxClassSize) { 

حاول قراءة الكود الآن. نحن لا نتحقق من "ما إذا كان عدد الطلاب أكبر من 23" ، ولكن "ما إذا كان هناك طلاب أكثر من الطلاب الذين يستوعبون الفصل".

استخدم أسماء واضحة للمتغيرات

لا أعرف السبب ، لكن قبل أن أخشى دائمًا إنشاء أسماء متغيرة. الذي كان غبيًا بالنسبة لي ، لأن rStuNms و fStuNms فظيعان مقارنةً بـ r awStudentNames و filteredStudentNames .

هل لا تزال هذه الأخيرة طويلة؟ ثم فكر في هذا: بعد أسبوعين من العطلة والعمل مع رمز آخر ، ستنسى نصف الاختصارات. وهي القدرة على قراءة أسماء المتغيرات أثناء التنقل هي القدرة على قراءة التعليمات البرمجية أثناء التنقل:

 const fStuNms = stus.map(s => sn) //    const filteredStudentNames = students.map(student => { return student.name; }); 

نصيحة جيدة أخرى هي استخدام اصطلاحات (اصطلاحات التسمية). إذا كان المتغير Boolean ، فابدأ اسمه بـ أو له ( isEnrolled: true ). إذا كان المتغير عبارة عن صفيف ، فاستخدم الجمع ( الطلاب ). يجب أن تبدأ العديد من الأرقام بالحد الأدنى أو الحد الأقصى . ويجب أن تحتوي أسماء الوظائف على فعل ، على سبيل المثال ، createSchedule أو updateNickname . يتحدث عن الميزات ...

اكتب وظائف صغيرة تسمى

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

يستغرق بضع ثوان للنظر في هذا الرمز ونقول ما يفعله:

 const handleSubmit = (event) => { event.preventDefault(); NoteAdapter.update(currentNote) .then(() => { setCurrentAlert('Saved!') setIsAlertVisible(true); setTimeout(() => setIsAlertVisible(false), 2000); }) .then(() => { if (hasTitleChanged) { context.setRefreshTitles(true); setHasTitleChanged(false); } }); }; 

الآن تفعل الشيء نفسه بالنسبة للرمز:

 const showSaveAlertFor = (milliseconds) => () => { setCurrentAlert('Saved!') setIsAlertVisible(true); setTimeout( () => setIsAlertVisible(false), milliseconds, ); }; const updateTitleIfNew = () => { if (hasTitleChanged) { context.setRefreshTitles(true); setHasTitleChanged(false); } }; const handleSubmit = (event) => { event.preventDefault(); NoteAdapter.update(currentNote) .then(showSaveAlertFor(2000)) .then(updateTitleIfNew); }; 

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

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

إضافة وصف اختبار مفيد

ربما أقل الحديث عن اختبارات موثقة ذاتيا ، ولكن دون جدوى.

دعنا نقول لدينا وظيفة مثل هذا:

 const getDailySchedule = (student, dayOfWeek) => { 

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

محاولة دمجها في تعليق هي فكرة سيئة: سيصبح التعليق قديمًا وليست حقيقة أنه سيتم تصحيحه في الوقت المناسب. هل تعرف أين يكون تسجيل خوارزمية التشغيل مناسبًا؟ في الاختبارات:

 describe('getDailySchedule ', () => { it("   ", () => { it('  ,   ', () => { it('     ', () => { 

هذه هي الطريقة الأكثر أناقة للتعليق على الكود بدون تعليق في الكود.

خلاصة القول: سهولة القراءة أكثر أهمية من الذكاء

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