ما هو المصطلح الصحيح للوثائق التي نضعها فوق إعلان الطريقة مباشرة؟

Question

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

نفس الشيء الذي أصبح في النهاية وثائق أعضاء JavaDoc.

إنها ليست مجرد وثائق داخلية، ولست متأكدًا من أن "توثيق الرأس" سيكون مصطلحًا جيدًا.

لاحظ أنني أبحث عن مصطلح عام، وليس مصطلحًا خاصًا بلغة معينة (على سبيل المثال، Java/Perl)

Answer 1

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

Answer 2

وفي منظمتي نسميها طريقة أو وظيفة DOC-للتعليق. الوثائق على مستوى وظيفة وربما كان مصطلح أكثر تستخدم على نطاق واسع.

Answer 3

وأدعو دائما طريقة (أو وظيفة) تعليق، لتمييزه عن فئة أو ملف التعليقات.

Answer 4

وغالبا ما يشار إليه ومهنيا على أنه "متطلبات البند"، أو "شرط التأمين".

Answer 5

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

(وهذا لا يشكل ضمانة، بالطبع، لكنه تشجيع المبرمجين لأكل الخضروات الخاصة بهم. وهذا يعني المطور يمكن أن تتغير وثائق <م> في نفس الوقت و في نفس المكان التغييرات السلوك، بدلا من بعد وقوعها وفي مكان آخر).

Answer 6

وأنا أسميها تعليقات التعليمات البرمجية، بسيطة من هذا القبيل.