التوثيق مع التعليقات
مُقدَّم| English | المعنى |
|---|---|
| comment/ˈkɒment/ | تعليق |
التعليق لا يصلح معادلة نشطة
- للسعر 100، يقوم
total = price * 10 / 100;بحساب 10 حتى لو كان هناك تعليق يقول "المبلغ المدفوع بعد خصم百分之十". تعديل هذا الشرح لا يجعل التعبير يحسب 90. - غيّر التعبير النشط إلى
price * 90 / 100لحساب الدفع المقصود في هذا المثال بالأعداد الصحيحة. يمكن أن تكشف التعليقات عن سياسة مقصودة؛ تحقق من أن الكود يطبقها.
حدد النص المستبعد من الكود
//يبدأ تعليقاً ينتهي عند نهاية السطر./*يبدأ تعليق كتلة ينتهي عند*/التالية؛ تعليقات الكتلة لا تتداخل. الفواصل الداخلية داخل سلاسل النص تُعد نصاً، لذا"https://example.com"لا يبدأ تعليقاً.- نصوص التعليقات لا تُنفذ كجمل برمجية جافا. إضافة شرح منفصل يترك التعبير النشط دون تغيير؛ وضع
//قبل تعيين نشط يزيل ذلك التعيين من الكود المُجمَّع ويمكن أن يغير السلوك.
ضع وسوم Javadoc في أسطر منفصلة
- يمكن لم-comment توثيق
/** ... */الموجود مباشرة قبل الإعلان أن يتم معالجته بواسطة Javadoc. ملخصه يشرح العملية؛ تبدأ الوسوم الكتلية مثل@paramو@returnفي أسطرها الخاصة بعد مسافة بيضاء اختيارية و*. - الفئة الكاملة أدناه توثق نصف قطر غير سالب وتُرجع مساحة الدائرة. تصف الوسومات المدخلات والمخرجات والمدخل المرفوض؛ لا يفرض التعليق وحده الشرط المسبق، لذا يتحقق الطريقة صراحةً من أنوف نصف القطر.
/** Circle-area calculations for finite radii. */
public class AreaDoc {
/**
* Returns the area of a circle for a finite radius.
* @param r the non-negative radius
* @return the area in squared radius units
* @throws IllegalArgumentException if r is negative
*/
public static double area(double r) {
if (r < 0) {
throw new IllegalArgumentException("Negative radius");
}
return Math.PI * r * r;
}
}
يعترف Javadoc بـ @param كتاج كتلة عندما يكون مدمجاً بعد النص الملخص في نفس السطر.
Difficulty 1/5 · 100 coins + a small bonus on first completion today
يبدأ تاج الكتلة سطره الخاص بعد مسافة بيضاء اختيارية ونجمة ابتدائية اختيارية. استخدم التعليق متعدد الأسطر الموضح.
اشرح القرار الذي لا يستطيع القارئ رؤيته
- قد ينص تعليق الخصم المفيد على "الدفع هو 90٪ من السعر المدرج؛ يستخدم هذا التمرين أسعاراً بأعداد صحيحة". هذا يوضح السياسة والافتراضات، بينما
// multiply by 90يعيد مجرد عملية. - ملخص العامد العام مفيد حتى عندما يكون جسمه قصيراً: يحتاج المتصلون إلى عقده دون دراسة التنفيذ. يفضل الشرح الذي يزود السياق الناقص بدلاً من إعلان كل تعليق وصفي زائداً.
عند تشغيل برنامج Java، التعليقات تكون...
Difficulty 1/5 · 100 coins + a small bonus on first completion today
التعليقات للبشر — Java تتجاهلها.
أي شيء يبدأ تعليقاً سطر واحداً في Java؟
Difficulty 1/5 · 100 coins + a small bonus on first completion today
// يعمل حتى نهاية السطر؛ /* */ هو كتلة.
أي نمط تعليقات تحوله الأدوات إلى توثيق للواجهة البرمجية (API)؟
Difficulty 1/5 · 100 coins + a small bonus on first completion today
Javadoc /** */ مع @param/@return تولد توثيق للواجهة البرمجية (API).
إضافة تعليق توضيحي بجانب معادلة فعالة غير متغيرة يصلح حسابها.
Difficulty 1/5 · 100 coins + a small bonus on first completion today
خطأ: التعليقات التوضيحية ليست تعبيرات برمجية. تعطيل تعبير برمجي يمكن أن يغير السلوك، ولكن هذا يعني تغيير الكود النشط فعلياً.
التعليقات الجيدة تشرح لماذا، بدلاً من إعادة نص ما يفعله الكود بوضوح.
Difficulty 1/5 · 100 coins + a small bonus on first completion today
علّق على النية، وليس على الواضح.
تحقق من الوثائق مقابل التنفيذ
- افترض أن التعليق يضمن رفض نصف القطر السالب، لكن الحارس تم حذفه. تصبح الوثائق خاطئة الآن على الرغم من أنها لا تزال تُنتج بنجاح؛ اختبر الإدخال السلبي بالإضافة إلى نصف قطر عادي.
- عندما يتغير السلوك، قم بتحديث التنفيذ وفحوصاته ووثائقه معًا. إنشاء صفحة API يتحقق من صحة صيغة الوثائق، وليس من صحة كل ادعاء فيها.
/** Returns an area. @param r radius @return area */ لا يضع وسوم الكتل في بدايات الأسطر المطلوبة. استخدم الصيغة متعددة الأسطر أعلاه، ثم افحص الأقسام المولدة للمعاملات والإرجاعات. التعليقات التوضيحية العادية ليست إصلاحات قابلة للتنفيذ.
هل التعليق مفيد أم لا؟
التعليقات الجيدة تشرح النية، وليس الواضح. رتب كل تعليق.
تنبؤ بتعيين معطّل
- ابدأ من
int x = 1;. مع تفعيلx = 5;، طباعة x تُنتج 5؛ استبدال هذا السطر بـ// x = 5;يُنتج 1. تغيير Statements النشطة يختلف عن إضافة ملاحظة بجانب statement غير متغير. - راجع ثلاث أسئلة بشكل منفصل: هل الحساب النشط صحيح؟ هل التوضيح يفسره بدقة؟ وهل وسوم Javadoc مُصنَّفة في أقسامها المقصودة؟ نجاح عملية الترجمة (compile) لا يجيب على جميع الأسئلة الثلاثة.
التعليقات تشرح الكود للقراء. الفواصل يمكنها استبعاد statements، بينما الملاحظات بجانب الكود النشط لا تصلح الحسابات. تبدأ وسوم كتل Javadoc على سطور مستقلة؛ احافظ على العقد الموثق متسقاً مع التنفيذ.
For a price of 100, type the amount paid after a ten percent discount.
Difficulty 1/5 · 100 coins + a small bonus on first completion today
The intended payment is 100−10=90. The misleading comment does not make the original expression calculate 90.
int x = 1; يتبعها // x = 5; في سطر منفصل. ما هي قيمة x التي سيتم طباعتها؟
Difficulty 2/5 · 140 coins + a small bonus on first completion today
التعيين إلى 5 مستبعد بواسطة التعليق أحادي السطر؛ يبقى x يساوي 1.