Yorumlarda totoloji ile nasıl başa çıkılır? [kapalı]

Bazen kendimi, yazdığım kodun bir kısmının (veya göründüğü gibi ) olduğu durumlarda, isminin temelde bir yorum olarak tekrarlanacağı açık bir şekilde ortaya çıkması durumunda buluyorum :

class Example
{
    /// <summary>
    /// The location of the update.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

(C # örneği, ancak lütfen soruyu dile agnostik olarak bakınız).

Böyle bir yorum işe yaramaz; Neyi yanlış yapıyorum? Yanlış olan isim seçimi mi? Böyle parçaları nasıl daha iyi yorumlayabilirim? Böyle şeyler için yorumu atlamalı mıyım?

Üzerinde çalıştığım çoğu projede, her sınıf üyesine ayrıntılı yorum yazmak için önemli bir süre yok.

Bu, yorum yapmak için zamanın olmadığı anlamına gelmez; Aksine, yorumlanmış olanın reprarasyonunu geri alan totolojik yorumlar için bolca zaman var. Bir başlangıç ​​noktası olarak harika çalışıyorlar .

Özellikle Visual Studio'nun IntelliSense’e eşlik eden yorumları kullanması durumunda , bu alanla ilgili kısa bir bilgi ile başlamak iyi bir fikirdir:

class Example
{
    /// <summary>
    /// The location of the update.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

Eğer kod, devam ettikçe Ve sonra sen olmadığını hatırlamıyorum güncelleme gerçekleşti konum veya güncelleme gönderiliyor yeri oldu, kodu tekrar gerekecek. Bu noktada şu ek bilgileri eklemelisiniz:UpdateLocation

class Example
{
    /// <summary>
    /// The Uri location where the update took place.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

Başka bir programcı size bir alandaki detayları sorarsa, bu bilgileri içeren yorumları güncelleyin:

Example.UpdateLocationSaklamak için ne tür bir güncelleme kullanılmalıdır?

class Example
{
    /// <summary>
    /// The Uri location where the Foo update took place.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

Tıpkı bir programın hataları olduğu gibi, iyi yorumlar da yinelemeli olarak çalışılması gereken hatalara sahiptir. Yorumların amacı, altı ay sonra tekrar ziyaret ettiğinizde kodun anlaşılmasına yardımcı olmak ve programın nasıl çalıştığı hakkında hiçbir şey hatırlayamamaktır.

Ve aynı programlama gibi, yorumlarınız bir yerden başlamalıdır. Tautolojik yorumlar Hello World!yorumlardır, dokümantasyon yazmayı ve güncellemeyi uyguladığınız için, başlangıç ​​dokümantasyonunuz gittikçe daha esnek olacaktır.

Yorumlar , kodunuzu asla çoğaltmamalıdır. Yorumlar “ nasıl? ” Sorusuna cevap vermemeli , sadece “ neden? ” Ve “ ne? ” Şeklinde cevap vermelidir . Neden böyle bir algoritma seçildiyse, burada örtük varsayımlar nelerdir (diliniz onu tür sistemi, sözleşmeler ve benzerleriyle ifade edebilecek kadar güçlü değilse), bu şeyi yapmanın nedeninin ne olduğunu vb.

İlham almak için Literatür Programlama uygulamasına bir göz atmanızı tavsiye ederim.

Yorumlar kodu açıklamalı , kopyalamamalıdır. Bu başlık yorumu sadece çoğaltılır. Dışarıda bırak.

Onları dışarıda bırak!

Normalde, içinde ifade edilen bilgilerin başka bir yerde mevcut olduğu yorumları kaldırmak iyi bir uygulamadır. Bir yöntemin amacını açık ve net bir şekilde iyi bir ad vererek ifade edebiliyorsanız, yorum yapmaya gerek yoktur .

Onları içeri sok!

Örneğiniz bu kuralın iki istisnasını gösterir:

İlk olarak, "UpdateLocation" (bağlama bağlı olarak) belirsiz olabilir. Bu durumda, daha iyi bir isim vermeniz veya belirsizliği gidermek için bir yorum yapmanız gerekir. Adı iyileştirmek genellikle daha iyi bir seçenektir, ancak bu her zaman mümkün değildir (örneğin yayınlanmış bir API uyguladığınızda).

İkincisi, C # içindeki "///", dokümanları otomatik olarak oluşturmak için kullanılması amaçlanan bir yorumu belirtir. IDE bu yorumları araç ipuçlarına kullanır ve yardım dosyaları oluşturabilen araçlar (Sandcastle) vardır. Bu nedenle, belgeledikleri metotların açıklayıcı isimleri olsa bile, bu yorumları eklemek için argümanlar var. Ancak o zaman bile, pek çok deneyimli geliştirici bilginin kopyalanması üzerine kaşlarını çattı. Karar faktörü, belgelerin amaçlandığı kişilerin ihtiyaçları olmalıdır.

"Yorum yazma" yanıtlarına kesinlikle katılmıyorum. Neden? Örneğinizi biraz değiştirerek işaret edeyim.

public Uri UpdateLocation ();

Peki bu işlev ne yapar:

• "Güncelleme konumu" döndürüyor mu? veya
• Konumu "günceller" mi ve yeni konumu döndürür mü?

Bir yorum olmadan belirsizlik olduğunu görebilirsiniz. Yeni başlayanlar kolayca hata yapabilir.

Örneğinizde, bir özellik olduğundan "get / set" yöntemleri ikinci seçeneğin yanlış olduğunu ortaya çıkarır ve gerçekten de "konumu güncelle" anlamına gelmez. Ancak bu hatayı yapmak, özellikle "güncelleme" gibi belirsiz sözler söz konusu olduğunda yapmak çok kolaydır. Güvenli oyna. Bunun için yeni birisini karıştırmayın, sadece zamanınızı birkaç saniye kurtarın

/// <summary>bloklar IntelliSense ve API dokümantasyonu için dokümantasyon oluşturmak için kullanılır .

Bu nedenle, eğer bu halka açık bir API ise, işlevin amacı okuyucular için açık olsa bile, her zaman en azından bir <summary>yorum içermelisiniz .

Ancak, bu kuralın istisnası; Genel olarak, sadece hatırlamak KURU (Do not tekrar) .

Böyle yorumlar doldurun, ancak böyle şeylerden nasıl faydalanacağınızı biliyorsanız; Aksi takdirde sadece silin.

_{Bana göre, açık bir fayda örneği, eksik yorumlar için otomatik bir kontrol yapıldığında ve bu kontrolün, önemli bilgilerin doldurulması gereken kodu tespit etmek için kullanıyordum; bunun için gerçekten bazı yer tutucuları dolduruyordum - sadece araç raporunun "yanlış alarmlar" içermediğinden emin olmak için.}

Bence her zaman bariz bir şekilde tekrar etmekten kaçınmanın bir yolu var . Yıllar geçtikçe sizinki gibi durumlar için çift "şablon dolguları" kullanmaya geldim - çoğunlukla kendi kendini tanımlayan adlar gibi ve yukarıya bakın .

Bu özel örnek için, “kendini tanımlayıcı türden” bir şeyler kullanırdım (silme işinin böyle bir şey yapmayacağı varsayılırsa), şöyle:

class Example
{
    /// <summary>
    /// Self descriptive method name.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

_{Örnek kullanabildiğimde yukarıdaki tür doldurucuları, dönüş değeri, parametreler ve istisnalar için özel alanlar gerektiren Javadoc yorumları olurdu . Oldukça sık, bunların hepsini veya hatta hepsini tek bir özet cümleyle tanımlamanın daha mantıklı geldiğini biliyorum; verilen parametreler için <neyin geri döndüğünü açıklar> (parametreleri tanımla>) döndüren yöntem . Bu gibi durumlarda, resmî olarak zorunlu alanları doldurup yukarıda açıklamayı görmek için yukarıyı işaretleyerek okuyunuz .}

İşte bir kod bölümüne yorum ekleyip eklememeyi düşünürken kendime sormak istediğim bir soru: Bir sonraki kişinin kodun genel amacını daha iyi anlamasına yardımcı olacak , böylece güncelleme, düzeltme veya daha hızlı ve daha güvenilir bir şekilde genişletmek?

Bazen bu sorunun doğru cevabı, kodun bu noktasında ekleyebileceğiniz fazla bir şey olmamasıdır, çünkü niyetini olabildiğince açık kılan isimleri ve kuralları zaten seçtiniz. Bu, sağlam bir kendi kendini belgeleyen kod yazdığınız anlamına gelir ve oraya bir yorum eklemek, yardımcı olabileceğinden fazlasını dağıtacaktır. (Gereksiz yorumların gerçekte zaman içinde gerçek kodla senkronizasyonun düşmesini yavaşlatarak ve böylece gerçek amacı çözmeyi zorlaştırarak kod güvenilirliğine zarar verebileceğini unutmayın.

Ancak, hemen hemen her programda ve herhangi bir programlama dilinde, orijinal programcı tarafından verilen belirli kritik kavramların ve kararların - sizin tarafınızdan - artık kodda görünmeyeceği noktalarla karşılaşacaksınız. Bu kesinlikle kaçınılmazdır, çünkü iyi bir programcı her zaman gelecek için programlar - yani, yalnızca programın bir kez çalışmasını sağlamak için değil, gelecekteki tüm düzeltmelerin, sürümlerin, uzantıların ve değişikliklerin ve bağlantı noktalarının ne olduğunu ve kimin ne yapılacağını da bilen ayrıca doğru çalışın. Bu ikinci hedefler dizisi daha zordur ve daha iyi düşünmeyi gerektirir. Ne işe yarar, diyerek üzerine, - işlevselliği odaklandık çoğu bilgisayar dilde iyi ifade etmek de çok zordur bu Programın sürümünü, şu anda, tatmin edici hale getirmek için yapmanız gerekir.

İşte ne demek istediğimin basit bir örneği. Çoğu dilde, küçük bir veri yapısının hızlı bir şekilde çevrimiçi olarak aranması, ilk defa bakıldığında birinin ne olduğunu hemen algılamayacak kadar karmaşık olacaktır. Bu iyi bir yorum için bir fırsattır, çünkü kodunuzun amacı hakkında daha sonra bir okuyucunun ayrıntıların çözülmesi için hemen yardımcı olabileceği bir şey ekleyebilirsiniz .

Tersine, mantık tabanlı dil Prolog gibi dillerde, küçük bir listenin aranmasını ifade etmek o kadar inanılmaz derecede önemsiz ve özlü olabilir ki, ekleyebileceğiniz herhangi bir yorum sadece gürültü olacaktır. Bu nedenle, iyi yorumlamalar mutlaka içeriğe bağlıdır. Bu, kullandığınız dilin güçlü yönleri ve genel program içeriği gibi faktörleri içerir.

Sonuç olarak bu: Geleceği düşünün. Programın gelecekte nasıl anlaşılması ve değiştirilmesi gerektiği konusunda kendinize neyin önemli ve net olduğunu kendinize sorun. [1]

Kodunuzun gerçekten kendi kendini belgeleyen kısımları için, yorumlar yalnızca gürültü ekler ve gelecekteki sürümler için tutarlılık sorununu arttırır. Yani onları oraya eklemeyin.

Ancak, kodunuzun çeşitli seçeneklerden kritik bir karar verdiğiniz veya kodun amacının belirsiz olduğu kadar karmaşık olduğu yerlerde, lütfen özel bilgilerinizi yorum biçiminde ekleyin. Böyle bir durumda iyi bir yorum, gelecekteki bazı programcıların neyin aynı kalması gerektiğini - bu da değişmez bir iddia kavramıdır - tesadüfen - ve neyin değişmesi gerektiğidir.

[1] Bu, yorum konusunun ötesine geçiyor, ancak bunun önemi var: Kodunuzun gelecekte nasıl değişebileceği konusunda çok net bir fikre sahip olduğunuzu fark ederseniz, muhtemelen sadece bir yorum yapıp bu parametreleri yerleştirmenin ötesinde düşünmelisiniz. Kodun kendi içinde, çünkü kodunuzdaki gelecekteki sürümlerin güvenilirliğini sağlamak için neredeyse her zaman daha güvenilir bir yol olacaktır; Aynı zamanda, fazla geleceği tahmin etmekten de kaçınmak istersiniz, çünkü insanlar geleceği önceden tahmin etmekte kötüydü ve program değişikliklerinin geleceğini de kapsıyor. Bu nedenle, tüm program tasarım seviyelerinde geleceğin makul ve kanıtlanmış boyutlarını tanımlamaya ve yakalamaya çalışın, ancak

Kendi kodumda, özellikle korkunç olanlar da dahil olmak üzere, yorum tautology'lerini sık sık yerinde bırakacağım:

<?php
// return the result
return $result;
?>

... Açıkçası, kodu açıklayıcı bir perspektiften daha anlaşılır hale getirmek için çok az katkı sağlıyor.

Yine de aklımda, sözdizimi vurgulayıcınızdaki renk desenlerinin görsel tutarlılığını korumaya yardımcı oluyorlarsa , bu yorumlar yine de değerlidir .

Kodun İngiliz diline çok benzeyen bir yapıya sahip olduğunu düşünüyorum, “cümle” ve “paragraflar” da var (“paragraf” tamamen tek bir “cümle” olsa bile). Genellikle her "paragraf" ın üstüne bir satır sonu ve bir satırlık özet eklerim. Örneğin:

<?php
//get the id of the thing
$id = $_POST['id'];

//query the things out of the the database
$things = array();
$result = mysql_query("SELECT * FROM Things WHERE `id` = $id");
while ($row = mysql_fetch_assoc($result)) {
    //create a proper Thing object or whatever
    $things[] = new Thing($row);
}

//return the things
return $things;
?>

(Eksik kodu, SQL enjeksiyonlarını vb. Dikkate almayın. Fikri elde edersiniz.)

Bana göre, nihai yorum koda gerçekten değer katıyor, çünkü tutarlı bir renklendirme planını koruyarak bir "paragrafı" diğerinden görsel olarak ayırmaya yardımcı oluyor.

Yorumlar, aşağıdakilerden birini yapmak için kullanılmalıdır.

1. Alınacak belge üreticilerinin bilgileri. Bu anlaşılamıyor, bu son derece önemlidir.
2. Neden bir kod parçasının bu şekilde olduğu ve diğer hususlarla ilgili uyarılar. 2 programlama dilinde yazılmış kodla uğraştım. Bunun önemli bir kısmı, iki dil arasında ortak bir yapıya sahip olmaktı. Her iki yerde de kullanıcıyı bu numarayı değiştirmeleri durumunda başka bir tane de değiştirmeleri gerektiğini bildiren bir yorum.
3. Neden tuhaf görünümlü bir kod parçasının böyle olduğunu açıklamak için notlar yazın. Belirli bir şekilde çalışmak için bir kod parçasını nasıl elde edeceğinizi düşünmeniz gerekiyorsa ve çözüm en baştan belli değilse, muhtemelen ne yapmaya çalıştığınızla ilgili bir açıklama yapmaya değecektir.
4. Açık değilse, giriş / çıkışları etiketleyin. Girişlerinizin ne olacağını ve hangi formatta olduklarını bilmek her zaman iyidir.

Yorumlar aşağıdakileri yapmak için kullanılmamalıdır:

1. Son derece açık olan şeyleri açıklayın. Eskiden böyle eski kodu gördü: page=0; // Sets the page to 0. Bence herhangi bir yetkin kişi bunu çözebilir.

Tatolojiyi kaldırırdım ama yorumu saklıyorum, örnek bir değer vererek özellikleri ve değişken isimlerini yorumlayacağım, böylece kullanım açıkça anlaşılıyor:

property UpdateLocation:TUpdateLocation;  // url="http://x/y/3.2/upd.aspx",proto=http

Şimdi tam olarak oraya ne girdiğini biliyorum ve yorumdan nasıl kullanılacağı konusunda net bir fikrim var.

Bunun yorumların amacına bağlı olduğunu söyleyebilirim.

Eğer bunu yapan ekip tarafından kullanılmak üzere dokümantasyon oluşturmak için kullanılacaklarsa (veya bir şeyi açıklamak için sadece satır içi yorumlarsalarsa), bunu dışarıda bırakmanın kabul edilebilir olduğunu düşünüyorum. Kendini açıklayıcı olduğu güvenle kabul edilebilir; ve olmadığında, yakınlarda açıklayabilecek başka ekip üyeleri de var. Elbette, eğer bir çok insan için belirgin olmadığı ortaya çıkarsa, onu eklemelisiniz.

Yorumlar coğrafi olarak uzak olan bazı ekipler için dokümantasyon üretecekse, her belgeyi oraya koyardım.

Bu konunun “yorumlar: anti-kalıplar” ya da “yorumlar bir kod kokusu mu?” Gibi isimler altında oldukça tartışıldığını düşünüyorum. ( bir örnek ).

Yorumların, kopya değil, yeni bilgiler eklemesi gerektiği genel fikrine katılıyorum. Bunun gibi önemsiz yorumlar ekleyerek, DRY'yi ihlal ediyor ve kodun sinyal / gürültü oranını düşürüyorsunuz. Sorumlulukları, arkasındaki gerekçeyi ve sınıfın örnek kullanımına göre mülk başına yapılan yorumlardan (özellikle gereksiz) çok daha kullanışlı olduğunu açıklayan üst düzey yorumlar bulma eğilimindeyim.

Şahsen, örneğinizde, yorumumdan çıkarım (mülk hakkında gerçekten yararlı bir şey yoksa).

Eğer yorum gerektirmeyen bir kod yazabilirseniz, programlama nirvana!

Kodunuz ne kadar az yorum kod gerektiriyorsa o kadar iyi olur!

Böyle bir yorum işe yaramaz; Neyi yanlış yapıyorum?

Sadece ne yaptığını zaten biliyorsan işe yaramaz görünüyor UpdateLocation. "Güncelleme" burada bir fiil veya isim eki midir? Yani, bu konumu güncelleyen bir şey mi, yoksa güncellemenin yeri mi? Biri, ikincisini UpdateLocationgörünüşte bir özellik olduğu gerçeğinden çıkartabilir , ancak daha büyük nokta, bazen açıkça görünen bir şeyi açıkça ifade etmenin zarar vermeyeceğidir.

Otomatik olarak derlenen dokümantasyon bir yana, kodun kendisini belgelemelidir, böylece yorumlar sadece kodun kendisini belgelemek için yeterli olmadığı durumlarda belgelendirilmelidir.

"Konum" biraz açıktır, ancak "Güncelleme" biraz belirsiz olabilir. Daha iyi bir isim yazamıyorsanız, yorumda daha fazla ayrıntı sunabilir misiniz? Neyin güncellemesi? buna neden ihtiyacımız var? Bazı varsayımlar nelerdir (boş bırakılabilir)?