شفرة المصدر تعليق نصائح التصميم وأفضل الممارسات

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

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

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

أنماط التعليق: نظرة عامة

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

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

مضمنة التعليق

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

/ / تبدأ قائمة متغير var myvar = 1 ؛ ... 

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

if (callAjax ($ params)) // بنجاح تشغيل callAjax بمعلمات المستخدم ... code

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

كتل وصفية

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

/ ** *desc يفتح نافذة مشروطة لعرض رسالة *param string $ msg - الرسالة المراد عرضها *return bool - النجاح أو الفشل * / function modalPopup ($ msg) … 

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

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

مجموعة / فئة التعليقات

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

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

/ ** *desc هذه الفئة ستحتوي على وظائف لتفاعل المستخدم * وتشمل الأمثلة user_pass () ، user_username () ، user_age () ، user_regdate () *author jake Rocheleau [email protected] *required settings.php * / فئة مجردة myWebClass  

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

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

تعليق الواجهة الأمامية

الآن وقد غطينا 3 نماذج تعليقات مهمة ، دعنا ننظر إلى بعض الأمثلة الأخرى. هناك العديد من مطوري الواجهة الأمامية الذين انتقلوا من HTML ثابت إلى jQuery و CSS code. لا تعد تعليقات HTML مفيدة للغاية مقارنةً بتطبيقات البرمجة ، ولكن عندما تكتب مكتبات النمط والبرامج النصية للصفحة ، يمكن أن تتعرض الأشياء للفوضى بمرور الوقت.

يتبع JavaScript طريقة أكثر تقليدية للتعليق مشابهة لـ Java و PHP و C / C++. يستخدم CSS فقط التعليقات على نمط الكتلة المحددة بشرطة مائلة ونجمة. يجب أن تتذكر أنه سيتم عرض التعليقات علنًا على زوار موقعك ، نظرًا لعدم تحليل CSS أو JS من جانب الخادم ، ولكن أيًا من هاتين الطريقتين تعمل بشكل رائع لترك الحكايات المفيدة في التعليمات البرمجية الخاصة بك للعودة.

تحديدا تقسيم ملفات CSS يمكن أن يكون عمل روتيني. نحن جميعًا على دراية بترك تعليق مضمن لشرح إصلاح لبرنامج Internet Explorer أو Safari. لكنني أعتقد أن تعليق CSS يمكن استخدامه على مستوى jQuery و PHP. دعنا نتعمق في إنشاء مجموعات أنماط قبل لمس بعض النصائح التفصيلية للتعليق على الكود.

مجموعات نمط CSS

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

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

• resets - أخذ الهوامش الافتراضية للمستعرض ، الحشو ، الخطوط ، الألوان ، إلخ.
• fonts - الفقرات ، العناوين ، blockquotes ، الروابط ، الكود
• navigation - روابط التنقل الرئيسية للمواقع الأساسية
• layout - المجمع والحاوية والأشرطة الجانبية
• header &footer - قد تختلف هذه حسب التصميم الخاص بك. تتضمن الأنماط الممكنة الروابط والقوائم غير مرتبة ، وأعمدة تذييل الصفحة ، والعناوين ، والملاحة الفرعية

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

/ **group footer * / #footer styles ...

/ **group footer ، خطوط صغيرة ، أعمدة ، روابط خارجية ** / 

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

4 نصائح لتحسين التصميم تعليق

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

1. حافظ على كل شيء مقروء

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

وظيفة getTheMail () / / رمز هنا سيبني البريد الإلكتروني / * رمز التشغيل إذا عاد استدعاء دالة sendMyMail () المخصص لدينا إلى العثور الحقيقي على sendMyMail () في /libs/mailer.class.php نتحقق مما إذا كان المستخدم يملأ جميع الحقول و يتم إرسال الرسالة! * / if (sendMyMail ()) return true؛ // حافظ على صدقك وعرض نجاحه على الشاشة

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

كقاعدة عامة من الإبهام, يستغرق بعض الوقت للتوقف والتأمل قبل الكتابة. اسال نفسك ما هو أكثر مربكة حول البرنامج و كيف يمكن أن تفسر ذلك بشكل أفضل في “غبي” لغة? يعتبر ايضا لماذا تكتب الكود كما أنت بالضبط.

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

2. التخفيف من بعض الفضاء!

لا أستطيع أن أؤكد بما فيه الكفاية مدى أهمية بيضاء يمكن ان يكون. هذا يذهب صحيح مضاعفة لمطوري PHP و Ruby الذين يعملون على مواقع ويب ضخمة بها مئات الملفات. سوف تحدق في هذا الرمز طوال اليوم! ألن يكون رائعًا لو تمكنت من الخروج إلى المناطق المهمة?

$ dir1 = "/ home /" ؛ // set main home directory $ myCurrentDir = getCurDirr ()؛ // قم بتعيين دليل المستخدم الحالي $ userVar = $ get_username ()؛ // اسم المستخدم الحالي للمستخدم

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

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

$ (document) .ready (function () $ ('. sub'). hide ()؛ // hide sub-navigation في pageload / ** تحقق من وجود نقرة على مرساة بداخل .itm div تمنع الرابط الافتراضي الإجراء حتى لا تتغير الصفحة عند النقر على الوصول إلى العنصر الأصل في .itm متبوعًا بقائمة .sub التالية للتبديل open / close ** / $ ('. itm a'). live ("click" ، وظيفة (e ) e.preventDefault () ؛ $ (هذا) .parent (). التالي ('. sub'). slideToggle ('fast')؛)؛)؛

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

3. التعليق بينما الترميز

جنبا إلى جنب مع التباعد المناسب قد يكون هذا واحدا من أفضل العادات للوصول إلى. لا أحد يريد العودة إلى برنامجهم بعد أن يعمل وتوثيق كل قطعة. معظمنا لا يريد حتى العودة وتوثيق المناطق المحيرة! انها حقا لا تأخذ الكثير من العمل.

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

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

4. التعامل مع أخطاء العربات التي تجرها الدواب

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

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

أخطاء التعليق مهمة لسببين رئيسيين. أولا يمكنك ذلك اختيار بسهولة من حيث توقفت و حاول مرة أخرى في الاعتبار لإصلاح المشكلة (المشاكل). وثانيا يمكنك ذلك التفريق بين إصدار الإنتاج المباشر لموقع الويب الخاص بك وأسباب الاختبار. تذكر أنه يجب استخدام التعليقات اشرح لماذا تفعل شيئا, ليس بالضبط ما يفعله.

استنتاج

يعد تطوير تطبيقات الويب والبرامج ممارسة مستوفية للرضا ، وإن كانت عملية صعبة. إذا كنت أحد المطورين القلائل الذين يفهمون حقًا بناء البرمجيات ، فمن المهم أن تنضج بمهارات الترميز. ترك التعليقات الوصفية هو مجرد ممارسة جيدة على المدى الطويل, ومن المحتمل أنك لن تندم أبدًا!

إذا كانت لديك اقتراحات لتعليق كود أكثر وضوحًا ، فأخبرنا بذلك في منطقة المناقشة أدناه!