Herhangi bir dilde tipik bir if-else-construct yazdığımda, yorum eklemek için en iyi yolun (okunabilirlik ve genel bakış açısından) ne olacağını merak ediyorum. Özellikle başka bir maddeyi yorumlarken, yorumlar her zaman benim için uygun değildir. Diyelim ki böyle bir yapımız var (örnekler PHP ile yazılmıştır):

if ($big == true) {
    bigMagic();
} else {
    smallMagic()
}

Ben böyle yorum yapabiliriz:

// check, what kind of magic should happen
if ($big == true) {
    // do some big magic stuff
    bigMagic();
} else {
    // small magic is enough
    smallMagic()
}

veya

// check, what kind of magic should happen
// do some big magic stuff
if ($big == true) {
    bigMagic();
}
// small magic is enough
else {
   smallMagic()
}

veya

// check, what kind of magic should happen
// if:   do some big magic stuff
// else: small magic is enough
if ($big == true) {
    bigMagic();
} else {
    smallMagic()
}

Bunu yorumlamak için en iyi uygulama örnekleriniz nelerdir?

İkisini de tercih ederim:

if ($magic == big) {
    bigMagic();
}
else {
    smallMagic();
}

veya:

if ($magic == big) {
    // big magic requires a big surprise, so I'm telling you about it here
    surprisingThing();
}
else {
    // give a magical feeling even if $magic is noMagicAtAll
    smallMagic();
}

Kod açıkça belirtmedikçe durumunuzun neyi kontrol ettiğini açıklayan bir yorum yazmak biraz saçma görünüyor. O zaman bile, mümkün olduğunca net hale getirmek için kodu yeniden yazmak daha iyidir. Aynı şey koşullu blokların gövdeleri için de geçerlidir - eğer bir şeyi açık bir şekilde yapmanın nedenini açıklayabilirseniz, yorum yapmak yerine bunu yapın.

"Asla yorum yazma" felsefesine abone değilim, ama kodun ne söylemesi gerektiğini söyleyen yorumlardan kaçınmaya inanıyorum. Kod söyleyebildiğinde "ne tür bir büyü olacağını kontrol et" gibi bir yorum yazarsanız if ($magic == big) {..., okuyucular yorumlarınızı çok hızlı bir şekilde okumayı bırakacaktır. Daha az, daha anlamlı yorumlar kullanmak yorumlarınızın her birine daha fazla değer verir ve okuyucuların yazdıklarınıza daha fazla dikkat etme olasılığı daha yüksektir.

Değişkenleriniz ve işlevleriniz için anlamlı adlar seçmek önemlidir. İyi seçilmiş bir ad, kodunuz boyunca açıklayıcı yorum yapma ihtiyacını ortadan kaldırabilir. Örneğinizde, $magicya da belki de örneğinize göre $kindOfMagicdaha iyi bir isim gibi görünüyor $big, bu bir şeyin "haberi" değil, test edilen "bir tür sihir" dir.

Kodda mümkün olduğunca çok şey söyleyin. Makul bir şekilde kod yazabileceğinizden daha fazla açıklama gerektiren durumlar için düzyazı kaydedin.

Açıklayıcı değişken adlarını deneyin

Yorumlar harika olabilir, ancak mümkünse kodu kendi kendine belgelendirin. Bunu yapmanın bir yolu açıklayıcı değişken isimleridir. Örneğin, bunun yerine:

if (user.has_sideburns && user.can_gyrate) {
  // This user is a potential Elvis impersonator

}

Adlandırılmış bir değişkeni tercih ederim:

is_potential_elvis_impersonator = user.has_sideburns && user.can_gyrate

if (is_potential_elvis_impersonator) {
  ...
}

Sadece bazı yorumları tamamlamak için:

Yorumların doğru kullanımı, kod içinde kendimizi ifade edemememizi telafi etmektir. Başarısızlık kelimesini kullandığımı unutmayın. Demek istedim. Yorumlar her zaman başarısızlıktır. Onlara sahip olmalıyız çünkü onlar olmadan kendimizi nasıl ifade edeceğimizi her zaman anlayamayız, ancak kullanımları kutlama için bir neden değildir. ( Temizlik Kodu Robert C. Martin tarafından )

BTW: Bu kitabı tavsiye ederim.

Yorumlar kodu yorumlamamalı ancak kodda olmayan şeyleri açıklamalıdır (daha büyük resim, neden, neden bir alternatif seçilmemiştir ...) Ve örnek yorumlarınız sadece şudur: kodun açıklaması.

Bazen elsedalın başında bir açıklama yapılması gerektiğini hissedebilirsiniz , ancak bu genellikle thendalınızın çok büyük olduğunun bir işaretidir .

Özel örneğinizde, yorumlar muhtemelen gerekli değildir. As Caleb söz kod açıkça yazılı ve eğer ifadeleri az olası yorumlama ihtiyacı varsa, değişkenler, semantik isimler var.

Snippet'inizi bununla karşılaştırın:

if ($x) {
    func1();
} else {
    func2();
}

Bu durumda, x, func1 ve func2'nin neyi temsil ettiğini açıklamak için yorumları kullanmak istersiniz (ve bu şema tarafından bir şeyler adlandıran kişiyi tokatlayın, özellikle de sizdiyseniz). $xBir boolean olup olmayacağını bile söyleyemezsiniz . Ancak bu da, yeniden düzenleme ve yeniden adlandırma yapabiliyorsanız, yorumlara ihtiyacınız olmadığı bir durumdur.

Genel olarak, kodun kendi başına yapamayacağı şeyleri açıklayan mantıksal bloklar için yorum yazmak istiyorum. Aşağıdaki bir avuç satırın daha yüksek bir soyutlama düzeyinde (örneğin // Make the right amount of magic happenörneğiniz için) neler yaptığını açıklayan her bir ~ 10-20 satırda bir astar, sizi yönlendirmeye yardımcı olur ve ne yaptığınıza ve ne zaman yaptığınıza dair yeni bir yorumcu sunar .

Aslında bu tek satırları kod yazmaya başlamadan önce yazıyorum, böylece segmentin sahip olması gereken akışı izlemiyorum.

Son olarak, kodun okunabilirliğine bakılmaksızın bir if bloğundaki cümleleri yorumlamayı gerçekten tercih ediyorsanız (veya gerektiren bir yetki varsa), şunu öneririm:

// Broad description of block
if (something) {
    //Do this because something
    something();
} else {
    //Do this because !something
    somethingElse();
}

Ben en temiz hissediyorum, çünkü yorum onunla ilgili kod ile sıraya. Hangi kodun açıklandığını açıklayan bir açıklama, açıkladığı açıklamaya olabildiğince yakın olmalıdır.

if (IsWeekDay(day))
{// weekday -> alarm at 7am
   ...
}
else if(day == DayOfWeek.Saturday)
{// saturday -> alarm at 11am
   ...
}
else
{// (sunday) -> no alarm
   ...
}

Parantezlerimi dizilmiş halde tutuyorum ve parantezin hemen arkasına koyuyorum.

[Condition] -> [pseudo-code]

Başka bir şey, teknik olarak diğer tüm koşulların başarısız olduğu anlamına gelir, bu yüzden genellikle parantez kullanıyorum.

([Condition]) -> [pseudo-code]

Not: Bu C # içindir.

Blok içinde ne yaptığını söyleyerek yorumları denemeye çalışıyorum (ilk örneğiniz).

Bu tür parçalanma nerede kullanırken elseif. Ben açık bir uç bloğu yoktur ve bu yüzden çok uzunsa yukarıdaki satırda (tabii ki satır kesmesi ile) devam eden durumun ne olduğunu kontrol etmek zorunda kalıyorum.

'Check XYZ
If Condition1 then
  'We need to do T and S
  DoCodeFor1();

'Check ABC
ElseIf Condition1 then
  'This requires something else to be done
  DoCodeFor2()

Else
  'We have no other option than to...
  DoCodeFor3()

End If

• Koşullu bloklarınızı gerçekten kısa tutun.
• Koşullu kodunuz basit bir satırdan iki satırdan fazla görünüyorsa, açıklayıcı bir ada sahip bir yöntemi çağırın.
• Değişkenleriniz için açıklayıcı adlar kullanın.
• Koşullu ifadenin anlamında açık olduğundan ve gizlenmiş veya uzun olmadığından emin olun. İşleri temiz ve okunabilir tutmaya yardımcı oluyorsa bir yöntem kullanın.

Yukarıdakilerin tümü başarısız olursa, niyetinizi açıklığa kavuşturmak için if ifadesinden önce çok küçük bir açıklayıcı yorum ekleyin. Aksi takdirde, gerçekten yorum yapmaya gerek yoktur.

C ++ veya C # 'da genellikle basit vakaları yorumlamazdım (ne olduğu açık olduğunda) ve bu tür bir stili son yorumu yapmak için kullanamazsınız ...

if (pattern == AAA)
{
  DoSomethingAAA();
}
else if (pattern == BBB)
{
  DoSomethingBBB();
}
else // if (pattern == CCC)
{
  DoSomethingCCC();
}