Kommentlər kodda

5.1 Şərhləri Necə Yazmalı

Python-da, çox proqramlaşdırma dillərində olduğu kimi, kodda şərhlər yazmaq olar. Şərhlər proqramçılara və layihənin digər iştirakçılarına kodu anlamağa kömək edir, xüsusilə də birgə iş və uzunmüddətli proqramın dəstəklənməsi zamanı faydalıdır. Python-da koda şərhlər əlavə etməyin bir neçə üsulu mövcuddur.

Tək sətirli şərhlər:

# simvolu ilə başlayır. Eyni sətirdə #-dən sonra gələn hər şey Python tərəfindən nəzərə alınmır. Bu tip şərhlər adətən müəyyən bir kod sətrinə dair qısa qeydlər və ya izahlar üçün istifadə olunur. Məsələn:

# Bu tək sətirli şərhdir
print("Salam, Dünya!") # Funksiyanın fəaliyyətinə dair izah

Çoxsətirli şərhlər:

Python-da çoxsətirli şərhlər üçün xüsusi bir sintaksis rəsmi olaraq yoxdur, ancaq onları bir neçə tək sətirli şərh istifadə edərək və ya üçlü dırnaq işarələrindən istifadə edərək yarada bilərsiniz. Halbuki, sonuncu, əslində, müstəqil kod kimi icra edilməyən çoxsətirli sətir literaldır. Məsələn:

# Bu çoxsətirli şərh nümunəsidir # Hər sətir # simvolu ilə başlayır
      

və ya:

""" Bu, şərh kimi istifadə oluna bilən bir çoxsətirli literaldır. Python bunu bir sıra kimi qəbul edir, amma bu sətir dəyişənə təyin edilmirsə və ya ifadədə istifadə olunmursa, heç bir şey etmir. """ 
      

5.2 Niyə şərhlər yazmalıyıq

Kodda şərhlərin istifadəsi onun oxunaqlığını artırır, dəstəklənməsini və yenilənməsini asanlaşdırır, həmçinin komandalar arasında daha effektiv əməkdaşlığa şərait yaradır. Şərhlər qısa, lakin informativ və aktual olmalıdır ki, kodun faydalı sənədləşdirilməsi kimi xidmət edə bilsin və onu lazımsız informasiyalarla "çirkləndirməsin".

Sənədləndirici sətirlər (docstrings):

Bunlar adətən modulların, siniflərin, metodların və funksiyaların əvvəlində yerləşən və onların təyinatını izah edən sətirlərdir. Onlar üçqat cüt dırnaq işarələri içində yazılır və avtomatik sənədləşdirmə üçün istifadə edilə bilər.

Nümunə:

def add(a, b):
""" İki ədədin toplanması funksiyası. :param a: birinci toplanan :param b: ikinci toplanan :return: a və b-nin cəmi """
    return a + b

Proqramlaşdırma dünyasında bəzən tərtibatçılar kodlarına şərhlər əlavə edirlər ki, bunlar yalnız izahat deyil, həm də təbəssüm yaradır. Kodda rast gəlinən bəzi məzəli şərhlərdən nümunələr:

Nümunə 1

 

            # Burada nə baş verdiyini izah edərdim, amma indi mənə belə aydın deyil.
        

Nümunə 2

 

    # Əgər bu işləmir, günah başqasındadır.

Nümunə 3

 

    # Gəldim, gördüm, düzəltdim... və dağıtdım.

Nümunə 4

 

    # Bu sətiri yazanda, bunu necə işlədiyini yalnız mən və Tanrı bilirdik. 
    # İndi isə yalnız Tanrı bilir.

Bu şərhlər inkişaf prosesinə yüngüllük və yumor qataraq kod bazasını daha az monoton edir. Onlar həmçinin xatırladır ki, proqram təminatının yaradılması yaradıcı və insani bir prosesdir.

5.3 Kodu tez bir şəkildə şərhə çevirmək

PyCharm-da kodu tez bir şəkildə şərhə çevirmək və ya şərhdən çıxarmaq üçün "hotkeys"-lərdən istifadə edə bilərsiniz. Bunun üçün dəyişmək istədiyiniz kod sətirlərini seçin və Windows-da Ctrl + / (və ya macOS-da Cmd + /) düymələrinə basın. Bu düymələr birləşməsi seçilmiş hər sətrin əvvəlində şərh işarəsi əlavə edir və ya onu silir, prosesi sürətli və effektiv edir.