Yorumlanan kod değerli belgeler olabilir mi?

Aşağıdaki kodu yazdım:

if (boutique == null) {
    boutique = new Boutique();

    boutique.setSite(site);
    boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
    boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
    boutique.setNom(fluxBoutique.getNom());
    boutique.setSelected(false);
    boutique.setIdWebSC(fluxBoutique.getId());
    boutique.setDateModification(new Date());

    boutiqueDao.persist(boutique);
} else {
    boutique.setSite(site);
    boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
    boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
    boutique.setNom(fluxBoutique.getNom());
    //boutique.setSelected(false);
    boutique.setIdWebSC(fluxBoutique.getId());
    boutique.setDateModification(new Date());

    boutiqueDao.merge(boutique);
}

Burada bir yorum satırı var. Ama bence ifve arasındaki farkın ne olduğunu açıkça ortaya koyarak kodu daha açık hale getirdiğini düşünüyorum else. Renk vurgulamada fark daha da belirgindir.

Böyle bir kodu yorumlamak iyi bir fikir olabilir mi?

Cevapların çoğu, bu özel olayı yeniden nasıl ele aldığına odaklanır, ancak kodun yorumlanmasının genellikle neden kötü olduğu konusunda genel bir cevap vereyim:

İlk önce, yorumlanan kod derlenmedi. Bu açık, ama bu demek oluyor ki:

1. Kod çalışmayabilir bile.

2. Yorumun bağımlılıkları değiştiğinde açıkça belli olmaz.

Yorumlanan kod çok "ölü kod". Orada ne kadar uzun süre oturursa, o kadar fazla çürür ve bir sonraki geliştiriciye daha az ve daha az değer sağlar.

İkincisi, amaç belirsizdir. Neden rastgele yorumlanmış satırlar bulunduğuna ilişkin bağlam sağlayan daha uzun bir yoruma ihtiyacınız var. Sadece yorumlanmış bir kod satırı gördüğümde, neden oraya girdiğini anlamak için oraya nasıl gittiğini araştırmalıyım. Kim yazdı? Ne taahhüdü? Taahhüt mesajı / içeriği neydi? Ve benzeri.

Alternatifleri düşünün:

• Amaç, bir fonksiyon / api kullanmanın örneklerini sağlamaksa, bir birim testi sağlayın. Birim testleri gerçek koddur ve artık doğru olmadıklarında kırılırlar.
• Amaç kodun önceki bir versiyonunu korumaksa, kaynak kontrolünü kullanın. Daha önceki bir sürümü kullanıma almayı tercih ederim, daha sonra bir değişikliği "geri almak" için kod tabanı boyunca yorumları değiştirdim.
• Amaç aynı kodun alternatif bir versiyonunu korumaksa, kaynak kontrolünü kullanın (tekrar). Sonuçta dalları bunun için var.
• Amaç yapıyı netleştirmekse, daha belirgin hale getirmek için kodu nasıl yeniden yapılandırabileceğinizi düşünün. Diğer cevapların çoğu, bunu nasıl yapabileceğinize güzel bir örnektir.

Bu kodla ilgili en büyük sorun, bu 6 satırı kopyalamanız. Bu çoğaltmayı ortadan kaldırdığınızda, bu yorum işe yaramaz.

Bir boutiqueDao.mergeOrPersistyöntem oluşturursanız, bunu şu şekilde yeniden yazabilirsiniz:

if (boutique == null) {
    boutique = new Boutique();
    boutique.setSelected(false);
}

boutique.setSite(site);
boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
boutique.setNom(fluxBoutique.getNom());
boutique.setIdWebSC(fluxBoutique.getId());
boutique.setDateModification(new Date());

boutiqueDao.mergeOrPersist(boutique);

Belirli bir nesneyi yaratan ya da güncelleyen kodlar yaygındır, bu nedenle örneğin bir mergeOrPersistyöntem oluşturarak bir kez çözmelisiniz . Bu iki durum için tüm atama kodunu kesinlikle çoğaltmamalısınız.

Birçok ORM bunun için bir şekilde destek sağlamıştır. Örneğin id, sıfır ise yeni bir satır oluşturabilir ve sıfır değilse varolan bir satırı güncelleyebilir id. Kesin biçim, söz konusu ORM'ye bağlıdır ve kullandığınız teknolojiye aşina olmadığım için size bu konuda yardımcı olamam.

Bir mergeOrPersistyöntem oluşturmak istemiyorsanız , kopyalamayı başka bir şekilde, örneğin bir isNewBoutiquebayrak ekleyerek ortadan kaldırmalısınız . Bu hoş olmayabilir, ancak bütün atama mantığını çoğaltmaktan çok daha iyidir.

bool isNewBoutique = boutique == null;
if (isNewBoutique) {
    boutique = new Boutique();
    boutique.setSelected(false);
}

boutique.setSite(site);
boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE + fluxBoutique.getLogo());
boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE + fluxBoutique.getUrl());
boutique.setNom(fluxBoutique.getNom());
boutique.setIdWebSC(fluxBoutique.getId());
boutique.setDateModification(new Date());

if (isNewBoutique)
    boutiqueDao.persist(boutique);
else
    boutiqueDao.merge(boutique);

Bu kesinlikle korkunç bir fikir. Niyenin ne olduğu belli değil. Geliştirici yanlışlıkla hattı yorumladı mı? Bir şeyi test etmek için mi? Neler oluyor?!

Her iki durumda da kesinlikle eşit olan 6 çizgiyi görmem dışında. Aksine, bu kod çoğaltmasını önlemelisiniz. Daha sonra bir durumda setSelected'ı ayrıca çağırdığın daha açık olacaktır.

Hayır, bu korkunç bir fikir. Bu kod parçasına dayanarak aşağıdaki düşünceler aklıma geldi:

• Bu satır, geliştiricinin hatalarını ayıkladığı ve satırı eski durumuna getirmeyi unuttuğu için yorumlandı.
• Bu satır, bir zamanlar iş mantığının bir parçası olduğu için yorumlandı, ancak artık geçerli değil.
• Bu satır, üretimde performans sorunlarına neden olduğu ve geliştiricinin üretim sistemi üzerindeki etkisinin ne olduğunu görmek istediği için yorumlanmıştır.

Binlerce satır yorum kodunu gördükten sonra, şimdi gördüğümde mantıklı olan tek şeyi yapıyorum: Hemen kaldırıyorum.

Yorumlanan kodu bir havuza teslim etmek için makul bir neden yoktur.

Ayrıca, kodunuz çok fazla çoğaltma kullanıyor. Bunu mümkün olan en kısa sürede insanın okunabilirliği için optimize etmenizi öneririm.

CodesInChaos'un cevabını eklemek isterim, bunu daha küçük yöntemlerle yeniden değerlendirebileceğinizi işaret ederek . Yaygın işlevselliği kompozisyonla paylaşmak, koşullardan kaçınır:

function fill(boutique) {    
  boutique.setSite(site);
  boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
  boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
  boutique.setNom(fluxBoutique.getNom());
  boutique.setIdWebSC(fluxBoutique.getId());
  boutique.setDateModification(new Date());
}    

function create() {
  boutique = new Boutique();      
  fill(boutique);
  boutique.setSelected(false);
  return boutiqueDao.persist(boutique);
}

function update(boutique) {
  fill(boutiquie);
  return boutiquieDao.merge(boutique); 
}

function createOrUpdate(boutique) {
  if (boutique == null) {
    return create();
  }
  return update(boutique);  
}

Bu açıkça kod yorumladı için iyi bir durum olmasa da, garanti olduğunu düşündüğüm bir durum var:

// The following code is obvious but does not work because of <x>
// <offending code>
<uglier answer that actually does work>

Bu, daha sonra görenlerin bariz iyileşme olmadığına dair bir uyarıdır.

Düzenleme: Küçük bir şeyden bahsediyorum. Büyükse bunun yerine açıklarsınız.

Bu özel örnekte, yorumlanan kodu büyük ölçüde Dibkke'nin cevabında belirtilen nedenlerden dolayı çok belirsiz buluyorum . Diğerleri, bir nedenden dolayı mümkün olmuyorsa (örneğin, satırlar benzer, ancak yeterince yakın değil), örneğin, bunu yapma eğiliminden kaçınmak için kodu yeniden düzenleyebileceğiniz yollar önerdi:

// Bu butik seçimini kaldırmaya gerek yok, çünkü [WHATEVER]

Bununla birlikte, kodun bırakılmasının (hatta yorum eklenmiş olsa bile) kodunun anlaşılmaz olmadığı bazı durumlar olduğunu düşünüyorum. MATLAB veya NumPY gibi bir şey kullanıldığında, çoğu zaman 1) bir dizi üzerinde yinelenen, bir anda bir öğe işleyen veya 2) tüm diziyi aynı anda çalıştıran eşdeğer bir kod yazılabilir. Bazı durumlarda, ikincisi daha hızlıdır, fakat okuması çok daha zordur. Bazı kodu vectorized eşdeğeriyle değiştirirsem, orijinal kodu yakındaki bir yoruma gömdüm, şöyle:

%% Aşağıdaki vectorized kodu bunu yapar:

% for ii in 1:N
%    for jj in 1:N
%      etc.

% ancak matris sürümü, tipik girdilerde ~ 15x daha hızlı çalışır (MK, 03/10/2013)

Açıkçası, iki versiyonun aslında aynı şeyi yapması ve yorumun ya gerçek kodla senkronize kalması ya da kod değişirse kaldırılması gerektiğine dikkat etmek gerekiyor. Açıkçası, erken optimizasyon hakkında her zamanki uyarılar da geçerlidir ...

Yararlı yorum kodu gördüğüm tek zaman, her seçeneğin kodunun sağlandığı, ancak yorumların kaldırılmasını sağlayarak ayarların etkinleştirilmesini kolaylaştıran config dosyalarındaydı:

## Enable support for mouse input:
# enable_mouse = true

Bu durumda, yorum kodu, kullanılabilir tüm seçeneklerin ve bunların nasıl kullanılacağının belgelenmesine yardımcı olur. Aynı zamanda varsayılan değerleri kullanmak da gelenekseldir, bu nedenle kod ayrıca varsayılan ayarları belgelemektedir.

Genel olarak konuşursak, kod yalnızca kodu yazan kişiye kendini belgelendirir. Dokümantasyon gerekiyorsa, dokümantasyon yazın. Bir kaynak kodu tabanındaki yeni bir geliştiriciden, neler olduğunu yüksek düzeyde anlamaya çalışmak için binlerce kod satırını okuyacak şekilde beklemek kabul edilemez.

Bu durumda, yorum yapılan kod satırının amacı, iki yinelenen kod örneği arasındaki farkı göstermektir. Farkı bir yorum ile daha sonra belgelendirmeyi denemek yerine, kodu yeniden yazıp anlamlı hale getirin. O zaman, hala kod hakkında yorum yapmak gerektiğini düşünüyorsanız, uygun bir yorum yazın.

Hayır, yorumlanan kodlar bayatlanır ve kısa sürede değersizleşir, uygulamanın bir yönünü ve mevcut tüm varsayımları beraberinde getirdiği için genellikle zararlıdır.

Yorumlar arayüz ayrıntılarını ve amaçlanan işlevi içermelidir; "amaçlanan işlev" şunları içerebilir: önce bunu deneyelim, sonra deneyelim, sonra başarısız olduk.

Gördüğüm programcılar yorumlarda bir şeyler bırakmaya çalışıyorlar, yazdıklarına aşık, bitmiş ürüne bir şey eklemiyor olsa bile kaybetmek istemiyorlar.

Çok nadir durumlarda olabilir, fakat yaptığınız gibi değil. Diğer cevaplar bunun sebeplerini oldukça iyi ortaya koydu.

Nadir durumlardan biri, dükkanımda tüm yeni paketlerin başlangıç ​​noktası olarak kullandığımız ve önemli bir şeyin dışarıda bırakılmadığından emin olmak için kullandığımız bir şablon RPM özelliğidir. Paketlerimizin çoğu, ancak standart bir adı olan ve bir etiket ile belirtilen kaynakları içeren bir tarball'a sahip değildir:

Name:           foomatic
Version:        3.14
 ...
Source0:        %{name}-%{version}.tar.gz

Kaynakları olmayan paketler için, standart formatı korumak ve birisinin geliştirme sürecinin bir parçası olarak sorunu durdurduğunu ve düşündüğünü belirtmek için etiketi yorumlayıp üzerine başka bir yorum koyarız:

Name:           barmatic
Version:        2.71
 ...
# This package has no sources.
# Source0:        %{name}-%{version}.tar.gz

Bildiğiniz kodları kullanmayacaksınız, çünkü başkalarının kapsadığı gibi, oraya ait bir şeyle karıştırılabilir. Yapabilir. ancak, neden bir kodun eksik olmasını beklediğini açıklayan bir yorum eklemek için yararlı olun:

if ( condition ) {
  foo();
  // Under most other circumstances, we would do a bar() here, but
  // we can't because the quux isn't activated yet.  We might call
  // bletch() later to rectify the situation.
  baz();
}

Yorumlanan kod uygulama tarafından kullanılmaz, bu yüzden neden kullanılmadığını belirten başka yorumlar da eşlik etmelidir . Ama bu bağlamda, orada olan yorumladı aşımı kod yararlı olabilir durumlar.

Aklıma gelen, bir sorunu ortak ve çekici bir yaklaşım kullanarak çözdüğünüz bir durumdur, ancak daha sonra gerçek sorununuzun gereksinimlerinin bu sorundan biraz farklı olduğu ortaya çıkmaktadır . Özellikle gereksinimleriniz çok daha fazla kod gerektiriyorsa, bakım verenlerin eski yaklaşımı kullanarak kodu "optimize etme" eğilimi büyük olasılıkla güçlü olacak, ancak bunu yapmak sadece hatayı geri getirecektir. “Yanlış” uygulamanın yorumlarda çevrede tutulması bunu ortadan kaldırmaya yardımcı olacaktır, çünkü bu durumda bu yaklaşımın neden yanlış olduğunu göstermek için kullanabilirsiniz .

Bu, çok sık meydana geldiğini hayal edebileceğim bir durum değil. Genellikle, örneklem "yanlış" bir uygulama içermeden olayları açıklamak yeterli olacaktır. Ama olabilir soru, yararlı olabilir, ister evet, olabilir yaklaşık olduğundan böylece, yeterli değil dava düşünün. Sadece çoğu zaman değil.

Bu iyi görünmüyor dostum.

Yorumlanan kod ... kod değil. Kod mantığın uygulanması içindir. Bir kodu kendi içinde daha okunaklı kılmak bir sanattır. @CodesInChaos zaten önerdiği gibi tekrarlayan kod satırları mantık çok iyi bir uygulama değildir .

Gerçekten gerçek bir programcının mantıksal uygulama yerine okunabilirliği tercih edeceğini düşünüyor musunuz? (bu arada, mantıklı temsilimize koymak için yorumlarımız ve 'tamamlayıcılarımız').

Endişelendiğim kadarıyla bir derleyici için bir kod yazmalı ve bu iyidir - eğer 'o' bu kodu anlarsa İnsan tarafından okunabilirliği için Yorumlar geliştiriciler için (uzun vadede), bu kodu tekrar kullanan kişiler için (örneğin, testciler) iyidir.

Aksi taktirde burada daha esnek bir şey deneyebilirsiniz.

butik.setSite (site) ile değiştirilebilir

setsiteof.boutique (site). Okunabilirliği artırabileceğiniz OOP'un farklı yönleri ve perspektifi vardır.

Bu kod ilk başta çok çekici görünmekle birlikte, bir kişi derleyici işini mükemmel bir şekilde yaparken bir yandan da insan tarafından okunabilirlik için bir yol bulduğunu düşünebilir ve bu uygulamayı izlemeye başlıyoruz. Zamanla ve daha karmaşık hale geleceği için daha karmaşık.