Pythonda kodni rasmiylashtirish. PEP 257
Pythonda kodni rasmiylashtirish – bu juda muhim yo`nalishdir, chunki, bunga sizning kodingizni boshqalar va hattoki o`zingiz ham bir oz vaqt o`tgach o`qish va tushunishning osonligi bog`liq bo`lib qoladi.
PEP257 Pythonda hujjatlashtirish satrlari bilan bog`liq kelishuv bo`lib, python kodni qanday hujjatlashtirish kerakligi haqida tushuncha beradi.
Ushbu PEPning maqsadi – hujjatlashtirish satrlari tuzilmasini standartlashtirish bo`lib, ularning tarkibida nimalar bo`lishi kerakligi, bularni qanday tavsiflash(hujjatlashtirish satrlarining sintaksisi bu yerda muhim emas) haqida so`z yuritiladi. Ushbu PEP qoidalar yoki sintaksis emas, balki kelishuvdan iboratdir.
Ushbu kelishuvlarga rioya qilinmagan hollardagi eng yomon oqibatlar – bazilarning sizga yomon qarab qo`yishlaridir. Lekin ba`zi dasturlar (masalan docutils) bu kelishuvlardan xabari bo`lib, ularga rioya qilish yaxshiroq natijalarga olib keladi.
Rasmiylashtirish satrlari deb nimaga aytiladi?
Rasmiylashtirish satrlari – bu satrli literallar bo`lib, modul, funksiya, klass yoki metodlarni aniqlashda birinchi joylashadigan operatorlar hisoblanadi. Bunday hujjatlashtirish satrlari shu ob`yektning __doc__ maxsus atributi bo`lib qoladi.
Odatda har bir modul hujjatlashtirish satrlariga ega bo`lishi kerak va mudul tomonidan eksport qilinadigan har bir funksiyalar va klasslar ham xuddi shunday hujjatlashtirish satrlariga ega bo`lishlair kerak. Ommaviy metodlar (shu jumladan, __init__) xuddi shunday hujjatlashtirish satrlariga ega bo`lishlari kerak. Modullar paketi __init__.py ga hujjatlashtirilishi mumkin.
Bir xillikka erishish maqsadida har doim hujatlashtirish satrlarida
“””triple double quotes“”” dan foydalaning. Agar siz hujjatlashtirish satrlarida teskari sleshdan foydalanadigan bo`lsangiz, r“””raw triple double quotes“”” dan foydalaning.
Hujjatlashtirish satrlarining 2 xil shakli mavjud.
Rasmiylashtirishning bir satrli ko`rinishlari
Bir satrliklar haqiqatdan ham oddiy bo`lgan holatlar uchun mo`ljallangan. Ular bir satrda joylashishlari kerak. Masalan:
def kos_root():
"""Return the pathname of the KOS root directory."""
global _kos_root
if _kos_root: return _kos_root
Agar matnlaringiz bir satrda joylashsa ham, uchtalik qo`shtirnoqlardan foydalaning. Keyinchalik qo`shimcha o`zgartirishlar kiritsh osonroq bo`ladi. Yopish qo`shtirnoqlari shu satrning o`zida bo`lsa, yaxshiroq ko`rinadi.
Hujjatlashtirish satrlaridan oldin va keyin bo`sh satrlar yo`q.
def function(a, b):
"""function(a, b) -> list"""
Bir satrli hujjatlashtirish funksiya yoki metodlar parametrlarining “imzosi” bo`lishi kerak emas. Quyidagicha qilish yaramaydi:
Hujjatlashtirish satrlarining bunday tipi faqatgina introspektsiya imkoniyatiga ega bo`lmagan C funksiyalar uchungina (tarkibiy modullar kabi) mos keladi. Lekin, shunga qaramay, qaytariladigan qiymatni introspektsiya yo`li bilan aniqlab bo`lmaydi. Bunday hujjatlashtirish satri uchun quyidagiga o`xshash variant ko`proq mos keladi.
def function(a, b):
"""Do X and return a list."""
(Albatta, “Do X” ni foydali biror tavsif bilan almashtirish kerak bo`ladi).
Dostları ilə paylaş: |