كود موثق ذاتيًا

في برمجة الحاسوب ، يتبع كل من الكود المصدري وواجهات المستخدم ذاتية التوثيق (أو ذاتية الوصف ) اصطلاحات التسمية واصطلاحات البرمجة الهيكلية التي تُمكّن من استخدام النظام دون معرفة مسبقة محددة. ^{[ 1 ]}

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

• اجعل قراءة وفهم شفرة المصدر أسهل ^{[ 2 ]}
• تقليل الجهد المطلوب لصيانة أو توسيع الأنظمة القديمة ^{[ 2 ]}
• تقليل حاجة مستخدمي ومطوري النظام إلى الرجوع إلى مصادر التوثيق الثانوية مثل تعليقات التعليمات البرمجية أو أدلة البرامج ^{[ 2 ]}
• تسهيل الأتمتة من خلال تمثيل المعرفة المستقلة

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

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

• توحيد اصطلاحات التسمية ^{[ 2 ]}
• الاتساق ^{[ 2 ]}
• نطاق التطبيق ومتطلبات النظام

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

size_t count_alphabetic_chars ( const char * text ) { if ( text == NULL ) return 0 ;size_t count = 0 ;بينما ( النص لا يساوي '\0' ) { إذا ( كان النص أبجديًا ) زد العداد بمقدار ++ ؛ النص بمقدار ++ ؛ }أعد العدد ؛ }

انتقد جيف راسكين الاعتقاد بمفهوم "التوثيق الذاتي" للبرمجيات، قائلاً إن البرمجيات لا تستطيع شرح الأساس المنطقي وراء كتابة البرنامج أو سبب تنفيذه بهذه الطريقة. ^{[ 3 ]}

• كلمة ذاتية
• سهولة قراءة الكود
• تعليق (برمجة الحاسوب)
• لغة طبيعية مضبوطة
• برمجة قائمة على الأدب
• برمجة اللغة الطبيعية

• ماكونيل، ستيف . "قائمة مراجعة الإجراءات عالية الجودة" . كود كومبليت .