1. Python tili imkoniyatlari Pythonni ko`chirish

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).