Python Yorumlarını Doğru Şekilde Oluşturun

Yorumlar, programcıların bu kodun ne yapması gerektiğini açıklamak için kodlarına ekledikleri notlardır. Kodu eyleme dönüştüren derleyiciler veya yorumlayıcılar, yorumları dikkate almazlar, ancak yazılım projelerini yönetmek için gerekli olabilirler.

Yorumlar, Python kodunuzu diğer programcılara açıklamaya yardımcı olur ve yaptığınız seçimleri neden yaptığınızı size hatırlatabilir. Yorumlar, geleceğin programcılarının yazılımın arkasındaki tasarım seçeneklerini anlamalarına yardımcı olarak hata ayıklamayı ve kodu gözden geçirmeyi kolaylaştırır.

Yorumlar öncelikle geliştiriciler için olsa da, etkili yorumlar yazmak, kodunuzun kullanıcıları için mükemmel belgeler oluşturmaya da yardımcı olabilir. Python projeleri için Sphinx gibi belge oluşturucuların yardımıyla, kodunuzdaki yorumlar belgeleriniz için içerik sağlayabilir.

Python'da yorum yapma başlığının altına bakalım.

Python'da yorumlar

Python PEP 8 Stil Kılavuzuna göre, yorum yazarken akılda tutulması gereken birkaç şey vardır:

• Yorumlar her zaman eksiksiz ve özlü cümleler olmalıdır.
• Anlaşılması zor veya yanlış olan bir yorumdansa hiç yorum yapmamak daha iyidir.
• Yorumlar, kodunuzdaki değişiklikleri yansıtacak şekilde düzenli olarak güncellenmelidir.
• Çok fazla yorum dikkati dağıtabilir ve kod kalitesini düşürebilir. Kodun amacının açık olduğu durumlarda yorumlara gerek yoktur.

Python'da bir satır, # simgesiyle başladığında açıklama olarak bildirilir. Python yorumlayıcısı kodunuzda # ile karşılaştığında, o sembolden sonrakileri yok sayar ve herhangi bir hata üretmez. Tek satırlık yorumları bildirmenin iki yolu vardır: satır içi yorumlar ve blok yorumları.

Satır İçi Yorumlar

Satır içi yorumlar, değişkenlerin ve basit işlemlerin kısa açıklamalarını sağlar ve kod ifadesiyle aynı satıra yazılır:

 border = x + 10 # Make offset of 10px

Yorum, kodun işlevini kodla aynı ifadede açıklar.

Yorumları engelle

Blok yorumları, koddaki karmaşık mantığı açıklamak için kullanılır. Python'daki blok yorumlar, satır içi yorumlara benzer şekilde oluşturulur — tek fark, blok yorumların ayrı bir satıra yazılmasıdır:

 import csv from itertools import groupby # Get a list of names in a sequence from the csv file with open('new-top-firstNames.csv') as f: file_csv = csv.reader(f) # Skip the header part: (sr, name, perc) header = next(file_csv) # Only name from (number, name, perc) persons = [ x[1] for x in file_csv] # Sort the list by first letter because # The groupby function looks for sequential data. persons.sort(key=lambda x:x[0]) data = groupby(persons, key=lambda x:x[0]) # Get every name as a list data_grouped = {} for k, v in data: # Get data in the form # {'A' : ["Anthony", "Alex"], "B" : ["Benjamin"]} data_grouped[k] = list(v)

Blok yorumları kullanırken, yorumların açıkladıkları kodun üzerine yazıldığını unutmayın. Python PEP8 Stil Kılavuzu, bir kod satırının yetmiş dokuzdan fazla karakter içermemesi gerektiğini belirtir ve satır içi yorumlar genellikle bu uzunluktaki satırları zorlar. Bu nedenle blok yorumları, kodu ayrı satırlarda açıklamak için yazılır.

Çok Satırlı Yorumlar

Python, çok satırlı yorumları yerel olarak desteklemez, bu da onları tanımlamak için özel bir hüküm olmadığı anlamına gelir. Buna rağmen, birden çok satıra yayılan yorumlar sıklıkla kullanılmaktadır.

Her satırın başına # koyarak birkaç tek satırlık yorumdan çok satırlı bir yorum oluşturabilirsiniz:

 # interpreter # ignores # these lines

Çok satırlı dizeler sözdizimini de kullanabilirsiniz. Python'da, çok satırlı dizeleri """ , üçlü çift tırnak veya ''' , üçlü tek tırnak içine alarak tanımlayabilirsiniz:

 print("Multi-Line Comment") """ This String is Multi line """

Yukarıdaki kodda, çok satırlı dize bir değişkene atanmamıştır, bu da dizenin bir yorum gibi çalışmasını sağlar. Çalışma zamanında, Python dizeyi yok sayar ve bayt koduna dahil edilmez. Yukarıdaki kodu çalıştırmak aşağıdaki çıktıyı üretir:

 Multi-Line Comment

Özel Yorumlar

Yorumlar, kodunuzu okunabilir hale getirmenin yanı sıra, Python'da gelecekteki kod eklemelerini planlamak ve belge oluşturmak gibi bazı özel amaçlara da hizmet eder.

Python Docstring Yorumları

Python'da dokümanlar, belirli bir işlevin veya sınıfın nasıl kullanılacağını açıklayan çok satırlı yorumlardır. Kodunuzun dokümantasyonu, yüksek kaliteli doküman dizilerinin oluşturulmasıyla geliştirilmiştir. Bir işlev veya sınıfla çalışırken ve yerleşik help(obj) işlevini kullanırken, nesneye genel bir bakış sağlamada belge dizileri yardımcı olabilir.

Python PEP 257, Python'da belge dizilerini bildirmek için aşağıda gösterilen standart bir yöntem sağlar:

 from collections import namedtuple Person = namedtuple('Person', ['name', 'age']) def get_person(name, age, d=False): """ Returns a namedtuple("name", "age") object. Also returns dict('name', 'age') if arg `d` is True Arguments: name – first name, must be string age – age of person, must be int d – to return Person as `dict` (default=False) """ p = Person(name, age) if d: return p._asdict() return p

Yukarıdaki kodda, docstring ilgili işlevin nasıl çalıştığına ilişkin ayrıntıları sağladı. Sphinx gibi dokümantasyon oluşturucularla, bu doküman dizisi, projenizin kullanıcılarına bu yöntemin nasıl kullanılacağına dair bir genel bakış sağlamak için kullanılabilir.

İşlevin veya sınıf imzasının hemen altında tanımlanan bir belge dizesi, yerleşik help() işlevi kullanılarak da döndürülebilir. help() işlevi, bağımsız değişken olarak bir nesne veya işlev adını alır ve işlevin belge dizilerini çıktı olarak döndürür. Yukarıdaki örnekte, get_person işleviyle ilişkili belge dizilerini ortaya çıkarmak için help(get_person) çağrılabilir. Yukarıdaki kodu -i bayrağını kullanarak etkileşimli bir kabukta çalıştırırsanız, bu belge dizisinin Python tarafından nasıl ayrıştırılacağını görebilirsiniz. python -i file.py yazarak yukarıdaki kodu çalıştırın.

help(get_person) işlev çağrısı, işleviniz için bir belge dizisi döndürür. Çıktı, Python'un otomatik olarak eklediği bir işlev imzası olan get_person(name, age, d=False) içerir.

get_person.__ doc__ özniteliği, belge dizilerini programlı olarak almak ve değiştirmek için de kullanılabilir. Yukarıdaki örnekte “Biraz daha yeni bilgi” ekledikten sonra, ikinci help(get_person) . Yine de, bunun gibi çalışma zamanında doküman dizilerini dinamik olarak değiştirmeniz gerekmeyecek.

YAPILACAKLAR Yorumlar

Kod yazarken, iyileştirme için belirli satırları veya tüm blokları vurgulamak isteyeceğiniz durumlar olabilir. Bu görevler, TODO açıklamaları tarafından işaretlenir. Kodunuzda güncellemeler veya değişiklikler planlarken veya proje kullanıcılarını veya ortak çalışanları dosyanın kodunun belirli bölümlerinin yazılmaya devam ettiğini bildirmek istediğinizde YAPILACAKLAR yorumları kullanışlıdır.

YAPILACAKLAR yorumları sözde kod olarak yazılmamalıdır — sadece henüz yazılmamış kodun işlevini kısaca açıklamaları gerekir.

YAPILACAK yorumları ve tek satırlık blok yorumları çok benzerdir ve aralarındaki tek fark, YAPILACAK yorumlarının TODO önekiyle başlaması gerektiğidir:

 # TODO Get serialized data from the CSV file # TODO Perform calculations on the data # TODO Return to the user

Pek çok IDE programcı için bu yorumları vurgulayabilse de, Python yorumlayıcısının TODO yorumlarını blok yorumlardan farklı görmediğini not etmek önemlidir.

Python Yorumları Yazarken En İyi Uygulamalar

Güvenilirliği ve kaliteyi sağlamak için yorum yazarken izlenmesi gereken bir dizi en iyi uygulama vardır. Aşağıda, Python'da yüksek kaliteli yorumlar yazmak için bazı ipuçları verilmiştir.

Açık Olandan Kaçının

Açıkça ifade eden yorumlardan kodunuza herhangi bir değer katmaz ve kaçınılmalıdır. Örneğin:

 x = x + 4 # increase x by 4

Bu yorum yararlı değildir, çünkü kodun neden yapılması gerektiğini açıklamadan ne yaptığını belirtir. Yorumlar, tanımladıkları kodun "ne"sinden çok "neden"ini açıklamalıdır.

Daha kullanışlı bir şekilde yeniden yazıldığında, yukarıdaki örnek şöyle görünebilir:

 x = x + 4 # increase the border width

Python Yorumlarını Kısa ve Tatlı Tutun

Yorumlarınızı kısa ve kolay anlaşılır tutun. Sözde kod yerine standart nesirde yazılmalı ve ne yaptığına dair genel bir genel bakış elde etmek için gerçek kodu okuma ihtiyacının yerini almalıdırlar. Çok fazla ayrıntı veya karmaşık yorumlar bir programcının işini kolaylaştırmaz. Örneğin:

 # return area by performing, Area of cylinder = (2*PI*r*h) + (2*PI*r*r) def get_area(r,h): return (2*3.14*r*h) + (2*3.14*r*r)

Yukarıdaki yorum, okuyucu için gerekenden daha fazla bilgi sağlar. Yorumlar, temel mantığı belirtmek yerine, kodun genel bir özetini sağlamalıdır. Bu yorum şu şekilde yeniden yazılabilir:

 # return area of cylinder def get_area(r,h): return (2*3.14*r*h) + (2*3.14*r*r)

Tanımlayıcıları Dikkatli Kullanın

Tanımlayıcılar yorumlarda dikkatli kullanılmalıdır. Tanımlayıcı adlarını veya durumlarını değiştirmek okuyucunun kafasını karıştırabilir. Misal:

 # return class() after modifying argument def func(cls, arg): return cls(arg+5)

Yukarıdaki yorum, hiçbiri kodda bulunmayan class ve argument bahseder. Bu yorum şu şekilde yeniden yazılabilir:

 # return cls() after modifying arg def func(cls, arg): return cls(arg+5)

KURU ve ISLAK

Kod yazarken, DRY (kendini tekrar etme) ilkesine bağlı kalmak ve WET'ten (her şeyi iki kez yazmak) kaçınmak istersiniz.

Bu aynı zamanda yorumlar için de geçerlidir. Kodunuzu açıklamak için birden çok ifade kullanmaktan kaçının ve aynı kodu açıklayan yorumları tek bir yorumda birleştirmeye çalışın. Ancak, yorumları birleştirirken dikkatli olmak önemlidir: birden çok yorumun dikkatsizce birleştirilmesi, stil kılavuzlarını ihlal eden ve okuyucunun takip etmesi zor olan çok büyük bir yorumla sonuçlanabilir.

Yorumların kodun okuma süresini kısaltması gerektiğini unutmayın.

 # function to do x work def do_something(y): # x work cannot be done if y is greater than max_limit if y < 400: print('doing x work')

Yukarıdaki kodda, yorumlar gereksiz yere parçalanmıştır ve tek bir yorumda birleştirilebilir:

 # function to do x if arg:y is less than max_limit def do_something(y): if y in range(400): print('doing x work')

Tutarlı Girinti

Yorumların, tanımladıkları kodla aynı düzeyde girintili olduğundan emin olun. Olmadıklarında, takip etmeleri zor olabilir.

Örneğin, bu yorum girintili değil veya düzgün konumlandırılmamış:

 for i in range(2,20, 2): # only even numbers if verify(i): # i should be verified by verify() perform(x)

Aşağıdaki gibi yeniden yazılabilir:

 # only even numbers for i in range(2,20, 2): # i should be verified by verify() if verify(i): perform(x)

Özet

Yorumlar, anlaşılır kod yazmanın önemli bir bileşenidir. Yorum yazmak için yaptığınız yatırım, gelecekteki kendinizin veya kod tabanınız üzerinde çalışması gereken diğer geliştiricilerin takdir edeceği bir yatırımdır. Yorum yapmak ayrıca kodunuzla ilgili daha derin içgörüler elde etmenizi sağlar.

Bu öğreticide, çeşitli Python yorum türleri, her birinin ne zaman kullanılacağı ve bunları oluştururken izlenecek en iyi uygulamalar dahil olmak üzere Python'daki yorumlar hakkında daha fazla şey öğrendiniz.

İyi yorumlar yazmak, üzerinde çalışılması ve geliştirilmesi gereken bir beceridir. Yorum yazma alıştırması yapmak için geri dönüp önceki projelerinizin bazılarına yorum eklemeyi düşünün. İlham almak ve en iyi uygulamaları iş başında görmek için GitHub'da iyi belgelenmiş Python projelerine göz atın.

Kendi Python projelerinizi hayata geçirmeye hazır olduğunuzda, Kinsta'nın Uygulama Barındırma platformu kodunuzu GitHub'dan saniyeler içinde buluta alabilir.