Python 3'te Yorumlar Nasıl Yazılır

Giriş

Yorumlar (comments), derleyiciler ve yorumlayıcılar tarafından göz ardı edilen bilgisayar programlarındaki satırlardır. Programlarda yorum kullanmak, kodun insanlar tarafından daha okunabilir hale gelmesini sağlar, çünkü programın her bir parçasının ne yaptığını açıklayan bazı bilgiler veya açıklamalar içerir.

Programınızın amacına bağlı olarak, yorumlar kendinize notlar veya hatırlatmalar olarak hizmet edebilir veya kodunuzu diğer programcıların anlamasını sağlamak amacıyla yazılabilir.

Genel olarak, bir programı yazarken veya güncellerken yorum yazmak iyi bir fikirdir, çünkü daha sonra düşünce sürecinizi unutmak kolaydır ve daha sonra yazılan yorumlar uzun vadede daha az faydalı olabilir.

Yorum Söz Dizimi

Python'da yorumlar, bir diyez işareti (#) ve bir boşluk karakteri ile başlar ve satırın sonuna kadar devam eder.

Bilgi: Bu eğitimdeki örnek kodları takip etmek için, yerel sisteminizde python3 komutunu çalıştırarak bir Python etkileşimli kabuğu (interactive shell) açın. Daha sonra örnekleri >>> isteminden sonra ekleyerek kopyalayabilir, yapıştırabilir veya düzenleyebilirsiniz.

Genellikle yorumlar şöyle görünür:

# Bu bir yorumdur

Yorumlar çalıştırılmadığı için, bir programı çalıştırdığınızda orada yorum olduğunu gösteren bir belirti görmezsiniz. Yorumlar, insanlar tarafından okunması için kaynak kodunda yer alır, bilgisayarlar tarafından çalıştırılması için değil.

Bir "Hello, World!" programında, bir yorum şu şekilde görünebilir:

hello.py

# Konsola "Hello, World!" yazdır
print("Hello, World!")

Bir listenin üzerinden geçen bir for loop döngüsünde yorumlar şöyle görünebilir:

sharks.py

# Sharks değişkenini bir dizi string olarak tanımla
sharks = ['hammerhead', 'great white', 'dogfish', 'frilled', 'bullhead', 'requiem']

# Sharks listesinin üzerinde döngü oluştur ve her bir string öğesini yazdır
for shark in sharks:
    print(shark)

Yorumlar, yorumladığı kod ile aynı girinti seviyesinde yapılmalıdır. Yani, girintisiz bir fonksiyon tanımı girintisiz bir yoruma sahip olacak ve her bir sonraki girinti seviyesi, yorumladığı kod ile hizalanmış yorumlara sahip olacaktır.

calculator.py

...
# again() fonksiyonunu kullanıcıya tekrar hesap makinesini kullanmak isteyip istemediğini sormak için tanımla
def again():

    # Kullanıcıdan girdi al
    calc_again = input('''
       Do you want to calculate again?
       Please type Y for YES or N for NO.
    ' ' ' )

    # Kullanıcı Y yazarsa, calculate() fonksiyonunu çalıştır
    if calc_again == ' Y ' :
        calculate()

    # Kullanıcı N yazarsa, kullanıcıya hoşçakal de ve programı sonlandır
    elif calc_again == 'N' :
        print('See you later. ')

    # Kullanıcı başka bir tuşa basarsa, fonksiyonu tekrar çalıştır
    else:
        again()

Yorumlar, programcıların, ister orijinal programcı olsun ister projeyi kullanan veya işbirliği yapan başka biri olsun, işini kolaylaştırmak için yapılır. Yorumlar kod tabanı ile birlikte düzgün bir şekilde bakım ve güncelleme yapılmazsa, çelişen veya çelişecek bir yorum yazmak yerine hiç yorum yapmamak daha iyidir.

Kod yorumlarken, kodun neden yapıldığını cevaplamaya çalışmalısınız, ne veya nasıl olduğunu değil. Kod özellikle zorlayıcı değilse, koda bakmak genellikle kodun ne yaptığını veya nasıl yaptığını gösterebilir.

Blok Yorumlar

Blok yorumlar, daha karmaşık kodu veya okuyucunun aşina olmayacağını düşündüğünüz kodu açıklamak için kullanılabilir. Bu daha uzun biçimli yorumlar, izleyen kodun tamamına veya bir kısmına uygulanır ve kodla aynı seviyede girintilenir.

Blok yorumlarda, her satır diyez işareti ve bir boşluk karakteri ile başlar. Birden fazla paragraf kullanmanız gerekiyorsa, bunlar tek bir diyez işareti içeren bir satırla ayrılmalıdır.

İşte aşağıdaki main() fonksiyonunda neler olduğunu tanımlayan bir blok yorum örneği:

# Ana fonksiyon, parser değişkeni aracılığıyla argümanları ayrıştıracaktır.
# Bu argümanlar kullanıcı tarafından konsolda tanımlanacaktır.
# Bu, kullanıcıya ayrıştırmak istediği kelime argümanını ve kullanmak istediği dosya adını iletecek ve
# kullanıcı doğru bir şekilde argümanları geçmezse yardım metni sağlayacaktır.

def main():
    parser = argparse.ArgumentParser()
    parser.add_argument(
        "word",
        help="metin dosyasında aranacak kelime."
    )
    parser.add_argument(
        "filename",
        help="içerisinde aranacak metin dosyasının yolu"
    )
...

Blok yorumlar, işlemler daha az anlaşılır olduğunda ve bu nedenle kapsamlı bir açıklama gerektirdiğinde tipik olarak kullanılır. Kodun aşırı yorumlanmasından kaçınmaya çalışmalı ve başka programcıların Python'u anladıklarına güvenmelisiniz, aksi takdirde belirli bir kitle için yazıyorsanız bu durum hariç.

Satır İçi Yorumlar

Satır içi yorumlar, bir deyimin aynı satırında, kodun hemen ardından gelir. Diğer yorumlar gibi, bunlar da diyez işareti ve bir boşluk karakteri ile başlar.

Genel olarak, satır içi yorumlar şöyle görünür:

[kod]  # Kod hakkında satır içi yorum

Satır içi yorumlar az kullanılsa da, karmaşık veya zorlayıcı kod parçalarını açıklamak için etkili olabilir. Gelecekte yazdığınız kodun bir satırını hatırlamayacağınızı düşünüyorsanız veya kodun tüm yönlerine aşina olmayan biriyle işbirliği yapıyorsanız yararlı olabilirler.

Örneğin, Python programlarınızda çok fazla matematik kullanmıyorsanız, sizin veya işbirlikçileriniz aşağıdakinin bir karmaşık sayı oluşturduğunu bilmeyebilir, bu yüzden bu konuda bir satır içi yorum eklemek isteyebilirsiniz:

z = 2.5 + 3j  # Bir karmaşık sayı oluştur

Satır içi yorumlar, bir şeyin neden yapıldığını veya ek bilgi sağlamak için de kullanılabilir:

x = 8  # x'i rastgele bir sayıyla başlat

Satır içi yapılan yorumlar, yalnızca gerekli olduğunda ve programı okuyan kişiye yardımcı olabileceğinde kullanılmalıdır.

Test İçin Kodu Yorumlama

Yorumları kodu belgelemek için kullanmanın yanı sıra, diyez işareti aynı zamanda oluşturduğunuz bir programı test ederken veya hata ayıklarken çalıştırmak istemediğiniz kodu yorumlamak için de kullanılabilir. Yani, yeni kod satırlarını ekledikten sonra hatalarla karşılaştığınızda, sorunu tam olarak belirlemek için birkaçını yorumlamak isteyebilirsiniz.

Diyez işaretini kullanmak, kodunuzu nasıl kuracağınıza karar verirken alternatifleri denemenize de olanak tanır. Örneğin, bir Python oyununda bir while loop döngüsü veya for döngüsü arasında karar verirken, testi ve hangisinin en iyi olduğunu belirlemek için birini veya diğerini yorumlayabilirsiniz:

guess.py

import random

number = random.randint(1, 25)

# number_of_guesses = 0

for i in range(5):
# while number_of_guesses < 5:
    print('1 ile 25 arasında bir sayı tahmin edin:')
    guess = input()
    guess = int(guess)

    # number_of_guesses = number_of_guesses + 1

    if guess < number:
        print('Tahmininiz çok düşük')

    if guess > number:
        print('Tahmininiz çok yüksek')

    if guess == number:
        break

if guess == number:
    print('Sayıyı tahmin ettiniz!')

else:
    print('Sayıyı tahmin edemediniz. Sayı ' + str(number) + ' idi.')

Kodu diyez işareti ile yorumlamak, farklı programlama yöntemlerini denemenize ve bir programın bölümlerini sistematik olarak yorumlayıp çalıştırarak hatanın kaynağını bulmanıza yardımcı olabilir.

Sonuç

Python programlarınızda yorum kullanmak, programlarınızın insanlar, özellikle de gelecekteki kendiniz için daha okunabilir olmasını sağlar. İlgili ve yararlı uygun yorumlar eklemek, diğerleriyle programlama projelerinde işbirliği yapmayı daha iyi hale getirebilir ve kodunuzun değerini daha net hale getirebilir.

Lisa Tagliaferri tarafından yazılan How To Write Comments in Python 3 Program makalesinin düzenlenmiş çevirisi

Daha Fazla Oku: