دليل الرسائل القصيرة السريعة للمطورين/توثيق البرنامج بستخدام inline و docstring

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

على سبيل المثال :

معايير كتابة البرمجية

مجتمع نظام الرسائل القصيرة السريع يتبع معايير PEP8 ؛انها اتفاقية لكيفية كتابة التعليمات البرمجية التي تضمن سهولة القراءة وسهولة المساهمة.

• ينبغي أن لا تحتوي الخطوط على أكثر من 79 حرفا.
• لا سطر جديد في نهاية الملف.
• فراغ واحد قبل وبعد العمليه.
• سطرين قبل الكائن أو الدالة.

ملاحظة هامة

def help(self, message):

        ''' Displays how to use the commands '''

        message.respond("Please enter :  [Surname,Name,Sex,Age(M:Male,F:Female)]")
        return True

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

./rapidsms shell

>> from apps.survey import app 
>> help(app.App.help )
     Help on method help in module apps.survey.app:    
     help(self, message) unbound 
    apps.survey.app.App method
    Displays how to use the commands

كان هذا مثل على كيفية توثيق الموديول ؛ الطريقة المثلى للتوثيق ليس فقط توثيق الموديول ولكن كتابة تعريف بسيط لتطبيق الذي قمت بإنشائه. مثال على كيفية كتابة معلومات عن برنامجك :

class App(rapidsms.app.App):

    ''' Survey RapidSMS App

        Handles an sms-collected survey
        help: Display the way you should write you SMS
        survey: command to enter the user profile information
        stat: returns number of records
        find: list of people in activity '''

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

| Survey RapidSMS App
|
| Handles an sms-collected survey
| help: Display the way you should write you SMS
| survey: command to enter the user profile information
| stat: returns number of records
| find: list of people in activity
|
| Method resolution order:
| App
| rapidsms.app.App
| rapidsms.component.Component
| __builtin__.object
|
| Methods defined here:
|
| find(self, message, keyw)
| returns list of people from one category
| Format: find CAT_CODE
| CAT_code is from Activity Model
|
| handle(self, message)
| Searchs for the right function and then call it
|
| help(self, message)
| Displays how to use the commands
|
| stat(self, message)
| returns the total Number of Profile in Database
| Format: stat
|
| survey(self, message, first, last, sex, age, Act)
| receivces from the user the requisted data to be inserted in DB
| Format : survey [ Your Profile information-be careful to write it in right order]