Nasıl Temiz Kod Yazılır Serisi | Bölüm 4 Yorumlar

[slowbaskan123]

İyi günler dilerim, bugün @'drose 'nin başlattığı;
Nasıl temiz kod yazılır serisine bir katkım olsun istedim.
Uzatmadan konuya geçelim.

Konumuz Yorumlar;

Yorumlar veya yorum satırları; koda anlam bütünlüğü kazandıran ve pratiklik için gereken bileşendir.
Yorumdan kastımız nedir, bakalım;

MockRequest request;
private final String HTTP_DATE_REGEXP =
"[SMTWF][a-z]{2}\\,\\s[0-9]{2}\\s[JFMASOND][a-z]{2}\\s"+
"[0-9]{4}\\s[0-9]{2}\\:[0-9]{2}\\:[0-9]{2}\\sGMT";
private Response response;
private FitNesseContext context;
private FileResponder responder;
private Locale saveLocale;

Programcıların yorumları güncel, alakalı ve doğru tutmak konusunda disiplinli olmaları gerekir.
Bir kodda, fonksiyon tanımlanmış veya bir değişken tanımlanmış peki neden?
İşte bunu yorumlar sayesinde açıklayın ki kodunuz "?" işareti kalmasın.

Peki yorumlar her zaman gereklimidir?
Yani bir koda yorum satırı eklemeden o kodun anlaşılması desteklenemez mi?
Buna bakalım;

// Çalışanın tam kapsamlı yardımlar için uygun olup olmadığını kontrol et
if ((employee.flags & HOURLY_FLAG) &&
    (employee.age > 65))

Bunun yerine daha açıklayıcı bir fonksiyonda kullanabiliriz;

if (employee.isEligibleForFullBenefits())

Bazı yorumlar gerekli veya faydalıdır.
Şimdi, bence yazılmaya değer birkaç yorum türüne göz atacağız.
Burada devreye Yasal Yorumlar giriyor.
Yasal yorumlar IDE'mizin başına eklediğimiz ve örnek olarak aşağıdaki gibi bir "reklam" anlamı taşıyan kod parçalarıdır;

// Copyright (C) 2003,2004,2005 by Object Mentor, Inc. All rights reserved.
// Released under the terms of the GNU General Public License version 2 or later.

Bazen bir yorum ile temel bilgileri sağlamak faydalı olabilir.
Örneğin, aşağıdaki yorum soyut bir metodun dönüş değerini açıklıyor;

// Test edilen Responder örneğini döndürür.
protected abstract Responder responderInstance();

Açıklayıcı kod dizelerine, eğitim için ve alışılagelmiş teknikler kullandığımızda başvuruyoruz.
Bir değeri "-" değil "+" döndürerek de doğru olduğunu, veya kodun anlam bütünlüğü bozuk gözüküyorsa bunu açıklamak için kullanıyoruz;

Formatı her zaman bu şekilde tutamayız veya tutmayız bu sebepten "özel" teknikler için direk yorum kullanmak size yardımcı olur.
Fakat tekniği açıklamak için illaki yorum gerekli değildir, fonksiyon ismini şu şekilde değiştirerek de koda anlam kazandırabilirsiniz;

protected abstract Responder responderBeingTested();

Artık bir yoruma gerek kalmadı çünkü;
Fonksiyon ismini tekniğe uygun hale getirdik.
Tekniği tam olarak açıklamak için her ikisini de kullanabilirsiniz.

Bazen bir yorum, sadece uygulamayla ilgili faydalı bilgiler sağlamanın ötesine geçer ve bir kararın arkasındaki amacı açıklar.

Aşağıdaki örnekte, önemli bir kararın yorum ile belgelenmiş olduğunu görüyoruz.
Bu kodda, iki nesneyi karşılaştırırken, kendi sınıfına ait nesneleri her zaman diğer nesnelerden daha büyük olarak sıralamak istiyoruz;

public int compareTo(Object o)
{
    if (o instanceof WikiPagePath)
    {
        WikiPagePath p = (WikiPagePath) o;
        String compressedName = StringUtil.join(names, "");
        String compressedArgumentName = StringUtil.join(p.names, "");
        return compressedName.compareTo(compressedArgumentName);
    }
    return 1; // Biz daha büyüğüz çünkü doğru türdeyiz.
}

Buradaki return 1; satırındaki yorum, bu kararın neden alındığını açıklıyor.
Yani, eğer karşılaştırılan nesne WikiPagePath türünde değilse, mevcut nesnenin daha büyük kabul edilmesi gerektiğini belirtiyor.
Amacımızda zaten verdiğimiz kararın doğruluğunu belirtmek.
Kodun pratiğinde her zaman aynı teknikleri kullanmıyoruz.
Teknikler her zaman değişebilir, önemli olan bizim aklımızdaki yeridir.

Farklı bir örneğe daha bakalım;

public void testConcurrentAddWidgets() throws Exception {
    WidgetBuilder widgetBuilder =
    new WidgetBuilder(new Class[]{BoldWidget.class});

Bu kod, eşzamanlı (concurrent) widget ekleme işlemini test ediyor.
Belki programcının bu soruna getirdiği çözümle aynı fikirde olmayabilirsiniz.
Siz sorunu (a+b) şeklinde çözerken, burada (a-b) şeklinde çözülmüş.
Ancak en azından ne yapmaya çalıştığını net bir şekilde anlayabiliyorsunuz.

Bu tür yorumlar, karmaşık kararların arkasındaki mantığı açıklamak açısından değerlidir ve kodun uzun vadede bakımını kolaylaştırır.
Belki de kodu yazarken ki odağınız ile şimdiki aynı değil, o an yapılan işlemleri hatırlamakta zorlanıyorsanız bu durumda en mantıklısı yaptığın işlemi kaydetmektir..

Bazen bir belirsiz argümanı veya dönüş değerini daha okunabilir bir hale getirmek için açıklayıcı bir yorum eklemek faydalı olabilir.

Genel olarak, bu argüman veya dönüş değerini doğrudan kendisi açıklayıcı olacak şekilde tasarlamak daha iyidir.
Ancak, eğer bu bir standart kütüphanenin parçasıysa veya değiştirme yetkinizin olmadığı bir koddaysa;
o zaman yardımcı bir açıklayıcı yorum eklemek kullanışlı olabilir.

String text = "'''bold text'''";
ParentWidget parent =
    new BoldWidget(new MockWidgetRoot(), "'''bold text'''");

AtomicBoolean failFlag = new AtomicBoolean();
failFlag.set(false);

// Bu, yarış koşulu oluşturmak için en iyi denememizdir
// Büyük sayıda iş parçacığı oluşturarak deniyoruz.
for (int i = 0; i < 25000; i++) {
    WidgetBuilderThread widgetBuilderThread =
        new WidgetBuilderThread(widgetBuilder, text, parent, failFlag);
    Thread thread = new Thread(widgetBuilderThread);
    thread.start();
}

assertEquals(false, failFlag.get());

Koddaki yorum, programcının bir yarış koşulu oluşturmayı amaçladığını net bir şekilde açıklıyor.
Eğer bu yorum eklenmemiş olsaydı, neden 25.000 iş parçacığının oluşturulduğu hemen anlaşılamayabilirdi.
Sizde bunun ne amaçlı kullanılacağını anlamayacaktınız.
Bu tür açıklayıcı yorumlar, özellikle karmaşık veya alışılmadık mantıkları içeren kod bloklarında oldukça faydalıdır.

Her zaman aklınızda 2 karşılaştırmanın sonucunu tutamazsınız.
Aşağıdaki örnek kod parçasına bakalım;

public void testCompareTo() throws Exception
{
    WikiPagePath a = PathParser.parse("PageA");
    WikiPagePath ab = PathParser.parse("PageA.PageB");
    WikiPagePath b = PathParser.parse("PageB");
    WikiPagePath aa = PathParser.parse("PageA.PageA");
    WikiPagePath bb = PathParser.parse("PageB.PageB");
    WikiPagePath ba = PathParser.parse("PageB.PageA");

    assertTrue(a.compareTo(a) == 0);  // a == a
    assertTrue(a.compareTo(b) != 0);  // a != b
    assertTrue(ab.compareTo(ab) == 0); // ab == ab
    assertTrue(a.compareTo(b) == -1);  // a < b
    assertTrue(aa.compareTo(ab) == -1); // aa < ab
    assertTrue(ba.compareTo(bb) == -1); // ba < bb
    assertTrue(b.compareTo(a) == 1);  // b > a
    assertTrue(ab.compareTo(aa) == 1); // ab > aa
    assertTrue(bb.compareTo(ba) == 1); // bb > ba
}

Elbette, açıklayıcı bir yorumun yanlış olma ihtimali önemli bir risktir.

Önceki örneği inceleyin ve yorumların doğruluğunu doğrulamanın ne kadar zor olduğunu görün.

Bu durum, hem neden açıklamanın gerekli olduğunu hem de neden riskli olduğunu açıklar.

Bu yüzden, böyle yorumlar yazmadan önce daha iyi bir yol olup olmadığını düşünmelisiniz.
Eğer gerçekten bir yorum eklemeniz gerekiyorsa, onların kesinlikle doğru olduğundan emin olmak için ekstra özen göstermelisiniz.
Yoksa temeli eksik binanın üstüne bir şey ekleyemezsiniz.
Bir kod parçası aklınızda yanlış kaldığı durumda o şekilde gider, tekrar düzeltmek zaman alır.
Bir yorumun doğruluğundan emin değilseniz, o yorumu silin ve kod parçasını inceleyin.

Bazen diğer programcıları belirli sonuçlar konusunda uyarmak faydalı olabilir.

Örneğin, aşağıdaki yorum bir test senaryosunun neden devre dışı bırakıldığını açıklıyor:

// Eğer boş vaktiniz yoksa çalıştırmayın!
public void _testWithReallyBigFile()
{
    writeLinesToFile(10000000);
    response.setBody(testFile);
    response.readyToSend(this);
    String responseString = output.toString();
    assertSubString("Content-Length: 1000000000", responseString);
    assertTrue(bytesSent > 1000000000);
}

Günümüzde ise bu tarz kodu yavaşlatabilecek işlemler yerine, @ignore etiketini kullanıyoruz.

@Ignore("Çalışması çok uzun sürüyor.")

Ancak JUnit 4'ten önce, bir test metodunun başına _ eklemek yaygın bir uygulamaydı.
Yorum asıl mesajı gayet iyi veriyor.
Bu durumda akılda kalıcılığı yüksek satırları kullanmakta size; "Bunu neden yapmamalıyım?" sorusunu aklınızda canlandırıyor.

Yapısı daha kritik bir örneğe bakalım;

public static SimpleDateFormat makeStandardHttpDateFormat()
{
    // SimpleDateFormat thread-safe değildir,
    // bu yüzden her örneği bağımsız olarak oluşturmalıyız.
    SimpleDateFormat df = new SimpleDateFormat("EEE, dd MMM yyyy HH:mm:ss z");
    df.setTimeZone(TimeZone.getTimeZone("GMT"));
    return df;
}

Buradaki yorum, çok önemli bir çoklu iş parçacığı (threading) sorununa dikkat çekiyor:
Bazıları daha iyi çözümler önerse de, bu yorum oldukça makul bir açıklama sağlar.
En azından, fazla hevesli bir programcının performans uğruna bir static başlatıcı (initializer) kullanarak hataya yol açmasını önleyecektir.
Bu şekilde programın hızını arttıracak ve kullanılan kaynaklara sınır getirecektir.

Bazen, "Yapılacaklar" (To do) notları bırakmak, //TODO yorumları şeklinde mantıklı olabilir.

Aşağıdaki örnekte, TODO yorumu, fonksiyonun neden bozuk bir implementasyona sahip olduğunu ve bu fonksiyonun gelecekte ne olacağını açıklıyor;

//TODO-MdM bunlar gerekli değil
// Check-out modelini uyguladığımızda bu işlevin kalkması bekleniyor
protected VersionInfo makeVersion() throws Exception
{
    return null;
}

Bu tür yorumlar, gelecekte yapılacak değişiklikler için bir hatırlatma sağlar ve geçici çözümler ile ilgili bilgi verir.

Genel olarak yorum satırlarının önemini anladık.
Projede akılda kalıcılık, kaynak kullanımını gibi gerekli şeyleri yorum satırları ile sağlayabiliyoruz.
Peki, bu yorum satırlarının kötü yanları yok mu?
Var elbette şimdide gelin Kötü Yorum Satırlarına bakalım;

Bu tür yorumlar, kodu o kadar gürültülü hale gelir ki, onları görmezden gelmeye başlarız.
Kodu okurken gözlerimiz onları geçip gider.
Sonunda, bu yorumlar kod etrafındaki değişikliklerle birlikte yanlış hale gelir.

Listing 4-4'teki ilk yorum uygundur gibi görünüyor.
Çünkü catch bloğunun neden göz ardı edildiğini açıklıyor.
Ancak ikinci yorum tamamen gereksizdir.
Görünüşe göre programcı, bu fonksiyonda try/catch blokları yazarken o kadar sinirlenmiş ki, biraz rahatlama ihtiyacı duymuş.
Boş ve gürültülü bir yorum yapmak yerine, programcı bu hayal kırıklığını kod yapısını iyileştirerek çözmeliydi.
Enerjisini, o son try/catch bloğunu ayrı bir fonksiyona çıkarmaya yönlendirebilirdi, tıpkı Listing 4-5'te gösterildiği gibi;

private void startSending()
{
    try
    {
        doSending();
    }
    catch(SocketException e)
    {
        // normal. birisi isteği durdurdu.
    }
    catch(Exception e)
    {
        try
        {
            response.add(ErrorResponder.makeExceptionString(e));
            response.closeAll();
        }
        catch(Exception e1)
        {
            // Biraz rahatlama!
        }
    }
}

Ne kadar gereksiz bir kod parçası, yorumlar yerine elbette ki anlamlı isimler kullanarak kodu anlaşılabilir biçime getirebiliriz.
Fakat yukarıdaki örnekte gereksiz try-catch blokları ve neden kullanıldığı belirsiz şekilde yazmadan bunu yapabiliriz.
Kodun temizlenmiş ve işlevi aynı haline bakalım;

private void startSending()
{
    try
    {
        doSending();
    }
}

Temiz, açıklayıcı bir biçimde yazılmış kodda görüntü kirliliği ve kafa karışıklığı sağlamayan sade bir kod parçası.
Bu yüzden kodunuzda her zaman açıklayıcı olmaya çalışın.
Fakat bunu yaparken gereksiz yere kodu uzatmayın ki, kafanız daha fazla karışmasın.

Javadocs da bazen gürültülü olabilir. Aşağıdaki Javadocs (iyi bilinen bir açık kaynak kütüphanesinden) ne amaçla yazılmıştır?
Cevap: Hiçbir şey. Sadece, belgeler sağlama isteğiyle yazılmış gereksiz ve gürültülü yorumlar.

/** The name. */
private String name;
/** The version. */
private String version;
/** The licenceName. */
private String licenceName;
/** The version. */
private String info;

Yine yorumlar ile kirletilmiş bir kod parçası.
Bu yorumları bir kez daha dikkatlice okuyun.
Kopyala-yapıştır hatasını görebiliyor musunuz?
Eğer yazarlar yorumları yazarken (ya da yapıştırırken) dikkat etmiyorsa, okuyucuların bu yorumlardan faydalanması beklenebilir mi?
Elbette beklenemez..

Yorumlar her zaman bir kod parçasını açıklamak için değil, bir belirteç gibide kullanılabilir.
Aşağıdaki kod örneklerinde olduğu gibi;

// Örnek //////////////////////////////////

// ------------------------- Örnek ------------------------

Nadir durumlarda, belirli işlevlerin bu tür bir banner altına toplanması mantıklı olabilir.
Ancak genel olarak, bunlar dağınıklık yaratır ve kaldırılmalıdır—özellikle sondaki gürültülü eğik çizgi sırası.

Bunu şöyle düşünün;
Bir banner, nadiren görüldüğünde çarpıcı ve belirgin olur.
Bu yüzden banner'ları çok az kullanmalı ve yalnızca faydası önemli olduğunda kullanmalısınız.
Eğer banner'ları aşırı kullanırsanız, arka plan gürültüsüne dönüşür ve görmezden gelinir.

InputStreamResponse response = new InputStreamResponse();
response.setBody(formatter.getResultStream(), formatter.getByteCount());
// InputStream resultsStream = formatter.getResultStream();
// StreamReader reader = new StreamReader(resultsStream);
// response.setContent(reader.read(formatter.getByteCount()));

O yorum satırına alınmış kodu gören başkaları, onu silmeye cesaret edemezler.
Orada bir sebep olduğu ve silmenin çok önemli olduğu düşüncesiyle kalır.
Bu yüzden yorum satırına alınmış kod, kötü bir kod parçası birikir.
Aşağıdaki ve yukarıdaki örnekler gibi;

this.bytePos = writeBytes(pngIdBytes, 0);
//hdrPos = bytePos;
writeHeader();
writeResolution();
//dataPos = bytePos;
if (writeImageData()) {
    writeEnd();
    this.pngBytes = resizeByteArray(this.pngBytes, this.maxPos);
}

Konu bu kadardır bölüm 4 bitti.
Şuan ki ilerleme oranımız 74 / 400

SAYGILARIMLA​

 

[ATE$]

Bu tarz konular cidden işe yarayabilen düzeyde. Teşekkürler konularınız için. Ellerinize sağlık.

 

[slowbaskan123]

Bu tarz konular cidden işe yarayabilen düzeyde. Teşekkürler konularınız için. Ellerinize sağlık.

Teşekkür ederim

 

[Kryzlo]

Teşekkür ederim, bunu da Github'dan aldım

Olsun hocam emeğiniz yeter

 

['drose]

eline saglik eklendi.

 

[slowbaskan123]

Olsun hocam emeğiniz yeter

eline saglik eklendi.

Teşekkür ederim.