Bir arkadaşım bana yöntemlerle yorum yazmanın iyi olmadığını söyledi. Sadece yöntem tanımları (javadocs) için yorum yapmamız gerektiğini, ancak yöntem gövdesinin içinde olmamamız gerektiğini söyledi. Bir kitapta, kodun içinde yorumların bulunmasının kodda bir sorun olduğu anlamına geldiği anlaşılıyor. Onun akıl yürütmesini tam olarak anlamıyorum. Yöntem gövdesine yorum yazmak iyi ve diğer geliştiricilerin bunu daha iyi ve daha hızlı anlamalarına yardımcı olduğunu düşünüyorum. Lütfen yorumlarınızı belirtin.
Arkadaşınız yanlış ve çok az programcı onunla aynı fikirde. Anlamaya en iyi yardım ettikleri her an ve her yerde yorum yazmalısınız.
Arkadaşını görmezden gel. Gerektiği gibi yorum yapın. Ancak kodunuzu açıklayıcı hale getirmeye çalışın, böylece yorumlar gerekli değildir gereklidir. Bilgisayarınızın yorum yapmadığını ve bu nedenle yorumların gerçekte olanlarla senkronize edilmesinin kolay olduğunu unutmayın.
Aksi takdirde okumak için biraz beyin bükülmesi gereken özellikle zor bir mantığı biraz açıklamak için bir yorum bloğu kullanma eğilimindeyim. Ve sonra mantığı daha açık hale getirmeye ve açıklama ihtiyacını ortadan kaldırmaya çalışacağım.
İyi kod kendi kendini belgelemektir. Bir yöntem tam olarak bir şey yapmalı ve bu şey yöntem adı ve yorum özellikleri ile açık olmalıdır. Bu nedenle, mantığı açıklayan yöntemde yorumlara ihtiyaç duyulması, yöntemin tek sorumluluk yöntemlerine ayrılması gerektiğini göstermektedir.
Şimdi, gerçeklik için. Karmaşık bir spagetti kodu kod tabanı ile karşı karşıyasınız ve koruyucular için iyi olmaya çalışıyorsunuz. 8 milyon kod satırını yeniden düzenlemek için zamanınız veya göreviniz yok ve bunu yapsanız bile nüanslar olurdu çünkü her şey karmaşık. Ne yaparsın?
Kaç kişinin bu görüşe katılmadığına şaşırdım.
Bununla birlikte, istisnalar var. Ama bunlar istisnalar. Ve mesele istisnalar, sayıca az olmaları. Gerçekten sadece sezgisel bir şey yapıyorsanız kod satır içi açıklamanız gerekir.
Metodunuzda yorumlara ihtiyaç duyabileceğiniz tipik bir durum, hızı optimize etmek için yerel bir hack uyguladığınız, ancak ilk okumada başka bir programcıya wtf anı verebileceğiniz durumdur. Yorum eklemek için iyi bir nokta.
Ama genel olarak: hayır, yöntemlerinize yorum eklemeyin.
Bence böyle bir vakadan bahsediyor:
public void upload() { // destination Host String Host = .... }
Yorum yerine daha açık bir değişken adına sahip olarak kodu daha iyi yapabileceğiniz yer:
public void upload() { String destinationHost = .... }
Arkadaşınızın Robert C. Martin tarafından "Temiz Kod" a atıfta bulunduğuna inanıyorum. Ancak, durumu biraz fazla basitleştirdiğini düşünüyorum. Kitap, hepimize bilmemiz gereken, ancak asla yeterince tekrarlanamayan yöntemlere açık ve açıklayıcı isimler vermekten bahsediyor. Kitap ayrıca, açık ve açıklayıcı bir ad verilebilen herhangi bir kod bloğunu kendi yöntemine sararak yöntemlerin çok küçük yapılmasını önermektedir. Dolayısıyla, bir kod bloğunun ne yaptığını açıklayan bir yoruma ihtiyacı olduğunu düşünüyorsanız, uygun bir adla ayrı bir yöntem yapmanız gerekir. Teoride, tüm yöntemleriniz 5 satırın altındaysa ve hepsinin iyi açıklayıcı isimleri varsa, bir yorumda açıklamak zorunda kalmadan ne yaptıkları açık olmalıdır.
Ancak, yöntemlerinizin içinde asla yorum yapmamanız gerektiği anlamına gelmez. Mesele şu ki, yorumlar gereksiz olmamalıdır. Bilgi eklemeliler. Tam olarak bir şey yapan bir yönteminiz varsa ve bu şey adından açıksa, ne yaptığını açıklayan bir yoruma ihtiyacınız yoktur. Ancak, işini neden bu şekilde yaptığını açıklayan bir yorum yapmak tam anlamıyla mantıklıdır. Neden bir algoritmayı diğerinin üzerine seçtiğinizi veya neden bir veri yapısını diğerine seçtiğinizi açıklayan bir yorum isteyebilirsiniz. Başka bir deyişle, kodun kendisinin nasıl çalıştığını açıklamasını ve yorumların tasarım kararlarınızın nedenlerini açıklamasını istiyorsunuz, i. e. neden bu şekilde yapılıyor.
Kitap, yorum yapmak yerine bozuk kodun yeniden düzenlenmesini önerir. Bu kesinlikle teoride harika bir fikirdir, ancak gerçekte bunu yapmak için uygun birim testleri setine sahip bir çalışma ünitesi test çerçevesi gibi zamana veya altyapıya sahip olmayabilirsiniz. Dün çalışmanız gereken dağınık bir kod tabanı ile karşı karşıya kaldığınız zamanlar vardır ve ilerlemenin tek yolu dağınık parçaları anlamaya çalışmak ve bunları kendiniz için notlar yapmanın bir yolu olarak yorumlamaktır.
Evet, kesinlikle Java'daki yöntemlerin içine yorum yazıyorsunuz.
Sun'ın kod kuralları dediği gibi:
Java programlarının iki tür yorumu olabilir: uygulama yorumları ve dokümantasyon yorumları. Uygulama yorumları C++ 'da bulunan ve
/*...*/, ve
//. Dokümantasyon yorumları ("doküman yorumları" olarak bilinir) yalnızca Java'ya aittir ve
/**...*/. Doc yorumları javadoc aracı kullanılarak HTML dosyalarına çıkarılabilir.
Yani, metotlardaki yorumlar uygulama yorumlarıdır.
Arkadaşınıza kesinlikle katılmıyorum ve satır içi işlev yorumlarının iyi kod yazmanın çok önemli bir parçası olduğunu iddia ediyorum. İşlev yorumları, kodun istemcilerine kodun ne yapması gerektiği - parametrelerinin ve dönüş değerlerinin ne anlama geldiği, giriş ve çıkışta olması beklenen değişmez çeşitleri vb. Hakkında daha iyi bir anlayış sağlamak için tasarlanmıştır. öncelikle kodun sahiplerine ve ideal olarak kodun orijinal yazarı için bir dizi zihinsel nota olarak yönlendirilir. Başka bir kişinin okuduğu karmaşık bir yönteme bakmayı ve orijinal yazarın ne düşündüğünü sezmeyi mümkün kılarlar. Ayrıca hataların teşhisini kolaylaştırırlar, çünkü yorumlar kodun amacının ne olduğunu ve hangi varsayımları açıklarsa, bir arıza tespit edildiğinde bir kod parçasının nasıl hatalı olduğunu anlamak çok daha kolay olabilir.
Şahsen satır içi yorumları yararlı buluyorum çünkü bana kendime yazmak üzere olduğum kodun doğru çalışacağını kanıtlamaya zorladım. Genellikle, ilk olarak niyetin ne olduğunu ve nasıl çalışacağını açıkça açıklamadan herhangi bir kod yazmamaya alışkanlık edeceğim. Daha fazla defa, bu kodda aptalca hatalar yapmamı engelliyor çünkü açıklamamın yanlış olduğunu veya bazı Edge olaylarını dikkate almadığını göreceğim.
Tabii ki, herkesin kendi kodlama disiplini vardır ve belki de bazı insanlar satır içi yorum yapmadan kod yazmayı ve kodu birden çok daha küçük yönteme ayırmayı daha kolay bulur. Ancak, deneyimlerimden dolayı, satır içi yorumlamanın geliştirme ve hata ayıklama sırasında çok değerli olduğunu ve başka bir projeye geçtikten sonra kodumu gözden geçirmesi ve sürdürmesi gereken diğer insanlar için son derece yararlı olduğunu buldum.
Arkadaşınız, yorumların kendileri "kod kokusu" değilse " deodorant " olduğu fikrini iyi ifade ediyor olabilir. Bu, yöntem içi yorumlara özgü değildir, ancak başlangıç yorumlarından daha yöntem içi yorumlarda daha doğru olma eğiliminde olabilir.
Bir yorum yazdığınızda, genellikle bir şeyi açıklamaktır. Bir şeyin açıklanması gerektiğinde - bu açıklayıcı değildir. Büyük kod is açıklayıcı. Dolayısıyla, yorum eklediğinizde, açıklayıcı hale getirmeden kendi kendini açıklama başarısızlığını örtbas edersiniz. Bu şekilde her yorum yazışınızda, yerine kodu değiştirerek - yeniden adlandırarak, yöntem çıkarma vb. İle - - make kendinden açıklamalı , idealin altında kalıyorsunuz.
Ama hepimiz tekrar tekrar mükemmellik eksikliği yaşıyoruz. Ve çoğu zaman açıklayıcı bir yorum eklemek, anlaşılması zor kodları belgelendirmeden bırakmaktan daha iyidir.
İyi yorumlar neden nasıl olduğunu açıklar. Buradaki temel ayrım bu. Çoğu insan ne yaptığınızı takip edebilecek, ancak neden yaptığınız ekstra yorum gerektiriyor. Bu yorumlar mümkün olduğunca operasyona yakın olmalıdır.
Kodunuzu (ya da bir başkasının gerçekten kötü belgelenmiş kodunu) yorumlarken, genellikle katıksız duygular ile karşı karşıya kalabilirsiniz iğrenme, nefret veya gazabı. Kod, sinir bozucu ve beklenmedik şekillerde davranabilir ve bazı son tarihler için çalışması için bazı kötü hack'ler eklemeniz gerekebilir.
Tüm bu durumlarda, ilgili kod kısımlarını bazı ağır küfürlerle ekleyerek duygularınızı ifade etmek (bkz. linux kernel fuckcount ) yaygın bir uygulamadır. Bu yorumlar, otomatik olarak belgelenen API'da görünmemesi için yöntemlerin içinde yaşamalıdır, böylece ne patronunuz ne de müşterileriniz veya başka bir kaynak kodu agnostik kişi bunu göremez.
Ancak diğer programcılarınız kaynak çalışırken rölyef ve mutluluk hissedeceklerdir. (Ve elbette kendinize notlar ekleyebilir veya kaynak kodunu bir ölçüde iletişim aracı olarak kullanabilirsiniz,
#TODO: add more examples here)
Tabii ki, bu tür yorumların ilk etapta orada olmaması gerektiğini veya son sürümden önce kaldırılmaları gerektiğini, ancak bu gün yazılım projelerinin çok kısa yayın döngülerine sahip olduğunu ve bazı yorumların hala alakalı olduğunu iddia edebilirsiniz. Birçok gece sonra inşa eder, bu yüzden arkadaşınız okuma (ve yazma) satırlar arasında öğrenmeye başlamalıdır.
Yorum gerektirmeyen bir kod olması güzel. Bir şeyleri aldığınızda, kaydettiğinizde ve sildiğinizde, neler olup bittiğine dair iyi bir fikrimiz var ve yorumlara gerek yok.
Bazen kod dağınık hale gelir ve yeniden düzenleme için bir adaydır, bu nedenle bu süre zarfında yorum yapmanız gerekebilir.
Bugün beklediğim şeyi yapmayan bir kod satırı vardı. Görünüşe göre bir .net veri tablosu, içe aktarılan bir satırın yeni bir kayıt olduğunu düşünmüyor. Kayıtları tablodan eklediğinizde hiçbir şey olmuyor. İçe aktarılan satırın önce durumunun değiştirilmesi gerekir. Basit bir yorum yeterlidir, bu yüzden 6 ay sonra ona geri döndüğümde ve "Bunun için neye ihtiyacım var?" Bileceğim.
Diğer programcılar için kodun ne yaptığını açık olmadığını düşündüklerinde, programcılar için yöntemlerin içine yorum koymak yaygın bir uygulamadır. Ayrıca Programcılar bazen metodun içine TODO yorumları koyarlar. Bununla birlikte, yöntemlerin içinde çok fazla yorumunuz varsa, geri çekilmeniz ve olması gerekenden çok karmaşık şeyler yapıp yapmadığınızı düşünmeniz gerekebilir. Diğer Word'de, muhtemelen onlarla kodu okumak daha zor olduğu için diğer programcılar için bariz bir şey hakkında yorum yapmaktan kaçınmak istersiniz.
Arkadaşlarınızın önerisini olumlu almak için, değişkenleri ve yöntemleri doğru şekilde adlandırarak çok fazla yorum yapmaktan kaçınabileceğimizi ve her yöntemi küçük tuttuğumuzu ve çok fazla personel yapmadığından emin olduğumuzu hatırlamanız gerekir.
Sanırım bunun nedeninin, işlevlerin her birinin yalnızca tek bir kavramsal işlemi kapsadığı kadar kısa olması gerektiğine inandığı için olduğunu düşünüyorum.
Mutlaka bu inanca aşırıya abone olmuyorum (çeşitli nedenlerden dolayı, bu kodu okumak kabus haline gelebilir), ancak biri olsaydı, işlev başına sadece bir yorum olacağını takip edebilirler, çünkü sadece fonksiyon başına bir kavram ve kavram başına bir yorum.
Her iki durumda da, seçimi veya davranışı hemen belirgin olmayan bir kod olduğunda ve genellikle performans değerlendirmeleri veya ezoterik matematikle ilgili olmak üzere yorumları kullanırım. Bu tür şeyler çoğu zaman işlevin tüketicisini hemen ilgilendirmez, bu yüzden aslında onu dokümantasyondan gizlemenin iyi bir fikir olduğunu iddia ediyorum.
Arkadaşınızın javadoc hakkında konuştuğuna inanıyorum, eğer bu yöntem beyanınızın üstünde ise (ve ekstra bir yıldız işareti ile dekore edilmişse) yorumunuzdan belgeler üretecektir:
/** get a webpage for a given url @param url: the url to get @returns String: the http-source */ public String getWebpage (String url) { ...
Bu yorumu yönteme koyarsanız işe yaramaz.
Bu nedenle - genel bir kural olarak: Java kaynak yöntemin üstüne yorum ekleyin).
İstisnalar olabilir ve olabilir. Kabul ediyorum: kısa yöntemler kullanmak, kendi kendine belgeleme kodu yazmak. Bununla birlikte, bir araç olarak javadoc yorumların tekrarlanmasını teşvik eder, çünkü dokümantasyonda çok çıplak görünüyor. :)
Sıfırdan yazılan bir yöntemde, bunun işlevini yalnızca başlık içinde belgeleyebileceği noktasını kabul ediyorum. Ancak.
Yorumların sık sık hataların keşfedildiği ve ince bir nüansın gözden kaçırıldığı yerlere eklendiğini görüyorum yöntemin sadece tek bir sorumluluğu olsa bile - dürüst olalım, eski kodda nadiren durum söz konusudur. Ayrıca, kısa bir değişken adı kısa bir değişken adı ile daha kolay sindirilebilir ve daha sonra tekrar kullanılabilir olduğunda, kırk karakter uzunluğunda (sadece iki yerde kullanılsa bile) değişken bir isme sahip olmak için hiçbir neden göremiyorum. Temiz ve özlü olmak en iyisidir, ancak her şeyden önce, e-postalar, mektuplar ve şiirler kadar diğer programcılarla da bir iletişim aracıdır. Ve buna alıntıyı ekliyorum:
“Bu mektubu daha uzun yaptım çünkü daha kısa yapmak için zamanım olmadı.”
Blaise Pascal, (1623-1662) Lettres eyaletleri
Yorumlar sadece kodu daha programcı dostu yapar, yorumların yürütülmeyeceğini unutmayın.
Birkaç ay sonra kodunuzu okuyacak olsaydınız, yorumlar kod üzerinden okumayı kolaylaştırır.
Kodu bakımı yapılabilir hale getirir ve koda bakan diğer tüm programcılar uyguladığınız mantığı anlamayı kolaylaştıracaktır.
Bu, birkaç satır kod içeren bir yöntem için bile her zaman yorum eklemeniz gerektiği anlamına gelmez.
Örneğin, aşağıdaki kod kendinden açıklayıcıdır ve işlevini netleştirmek için herhangi bir yorum gerektirmez
public String getName(){ return name; }
Bir yöntem büyük olduğunda, herhangi bir programcı baktığında daha okunabilir olması için yorum ekleyin.
Kodlama sırasında kodun kendinden açıklayıcı olduğunu düşünebileceğinizi unutmayın, ancak altı ay sonra baktığınızda, altı ay önce eklediğiniz yorumlar kesinlikle size veya başka bir programcının kodu hızlı bir şekilde anlamasına yardımcı olacaktır.
Satır içi yorumlarla ilgili sorun, kodla birlikte korunmaları gerektiğidir (işlev/yöntem/modül/sınıf düzeyinde yorumlar için de geçerlidir, ancak büyük ölçüde değil); Tanrı, yorumların artık belgeledikleri kodla kesinlikle hiçbir ilgisi olmadığı yerlerde, ne kadar kaynak kodunun olduğunu biliyor.
İdeal olarak, satır içi belgeler aşağıdaki durumlarla sınırlı olmalıdır:
Çok optimize edilmiş veya "zor" olan kodun açıklanmasıyla birlikte neden için bir gerekçe ile kodun çok fazla optimize edilmiş veya "zor" olduğunu açıklamak ("performans gereksinimi X'i kaçırıyorduk ve profilleme, darboğazın burada olduğunu gösterdi aşağıdaki optimizasyonlar% Y performans kazandı ");
Bir standarda veya gereksinime atıfta bulunarak ("DTED 0 post aralığı 30 ark saniyedir");
Daha fazla analiz/geliştirme gerektiren kodu belirleyin ("TODO");
Kod belgelemenin birinci yasası - açık olanı belgelemeyin. İlk kod dokümantasyonunun sonucu - mümkün olan en açık şekilde kod yazın.
İlk olarak, sorunuz özellikle Java odaklıydı - bu da cevabı önemli ölçüde etkiliyor.
zorunl olan yorum miktarı, içinde çalıştığınız dille oldukça ilgilidir.
Java ve C # gibi bazı diller, kendilerini belgeleme kodu kavramına son derece iyi uyum sağlarlar. yalnızca dilde yerel olarak tanımlayamadığınız şeyler için satır içi yorumlar eklemek.
SQL gibi bazı dillerin okunabilir hale getirilmesi daha zordur. Sözdizimi, değerlendirme sırası, iç içe yerleştirme vb. Kendi kendini belgeleyen bir şekilde tasarım yapmayı daha zor hale getirebilir. Aynı temel yaklaşım hala geçerlidir: dili mümkün olduğunca kullanmaya odaklanın, ardından belirsiz veya kafa karıştırıcı alanları telafi etmek için yorumlar ekleyin.
Genel olarak yorumları% 100 kaldıramazsınız, ancak amacınız kodu daha fazla kendi kendini tanımlayarak, mümkün olduğunca ihtiyaç kaldırmaktır. Bu çabaların sonuçları genellikle daha az kod genel ve daha iyi organize koddur. Hala yorum bulunup bulunmadığına bakılmaksızın, bu, kodunuzun çok daha sürdürülebilir ve ulaşılabilir olacağı anlamına gelir - bu, yorumların herhangi bir konuda yardımcı olmayı amaçladığı şeydir.
Javadoc'un (hatta Delphi otomatik tamamlama ipuçlarının) bir kişinin kodlama şeklini değiştirmesi gerektiği fikri (javadoc için işlevsellik eklemek dışında) oldukça saçma.
Önce gelen arkadaşınıza, javac veya javadoc'a sorun.
Bu hangisinin önce geldiğini sormak gibi, inek veya Bayan O'Leary
Ayrıca, javadoc sınıfınızı ve işlevlerinizi uygulayan insanlar için olmalı, koddaki yorumlar kodunuzu koruyan insanlar içindir. Özellikle özel yöntemlerinizle, hiç kimsenin ne yaptığını görmek için kodunuza bakması gerekmemelidir. Doktorlar bunun için. Ancak birisinin bir hata yüzünden kıllı olması nedeniyle bir şeyleri düzeltmesi gerekiyorsa, bunu yönteminizde yorumlamak istersiniz.
Açıkçası hata düzeltmelerinin hepsinin kötü olduğu kodun% 90'ını varsayıyor. "Pragmatik programcı" yı hiç okumadım ama o kitaba gönderme yapmadığını varsayabilirim.
Şimdi iki sentimi atacağım, parti oldukça bitti. Belirli bir iş mantığını açıklarken veya öngörülemeyen bir Edge vakasını kapsayacak bir şey eklemem gerektiğinde yorumları kullanıyorum.
Kod, önceden bilinmeyen şeyleri hesaba katmak için zaman içinde gelişir ve bu yüzden bir bant yardımı uyguladığınızda, bilindiği varsayılmak yerine neden bu bant yardımını koyduğunuzda, bazen yardımcı olur "oh, bu arada, bunu düzeltmek zorunda kaldım ve işte çevredeki konuşmayı takip edebilmeniz için bugtracker referansı" yazan küçük bir blok eklemek için ve benim durumumda (FogBugz kullandığım gibi) şöyle görünecektir :
//Case: 1234 ~ Throttling based on unusual activity per ABC request. Throttler myThrottler = new Throttler( oldActivity );
ya da her neyse. Demek istediğim, yerinde görünmeyen ve okunabilir olmayan bir şeyin muhtemelen satır içi belge için iyi bir yer olması. Toplanan bilgi güzel bir şeydir.
Ama ilk işim mantığımdı. Kelimenin tam anlamıyla önünde bazı iş kuralları olan bu AM yeniden yazmak üzereyim saklı bir yordamda bir blok var.
/**************************************************************** author yourstruly date 2010-11-18 descrip intended use is to blah blah blah ended up over actual measured blah blah blah according to blah blah blah rules from the customer are: If the sum of the blah blah blah is higher than the blah blah blah and the blah blah blah contain blah blah blah, and the blah blah blah is non-zero, recalculate the blah blah blah to fit within the blah blah blah Additional rules for us internally: if the blah blah blah originally read blah blah blah don't blah blah blah (set to zero) rewritten here with (1) traceable statements for the where clauses. If the blah blah blah(1) is higher than the blah blah blah (2) and the blah blah blah (3) and the blah blah blah is non-zero (9) and the blah blah blah is lower than the blah blah blah (4) and the edited blah blah blah is higher than the blah blah blah (5) then recalculate the blah blah blah (6) // See note lower in this document on the math If the blah blah blah(1) is higher than the blah blah blah (2) and the blah blah blah (3) and the blah blah blah is higher than the blah blah blah (7) then set the blah blah blah to zero (8) (7) dictates the same as (4) but it's easier to do (7) ****************************************************************/ Sorry for the blah blah blah's but proprietary rules and all that ;)
Ve birdenbire, kodumda yorum olarak gömülü gereksinimlerim (!) Olduğunu görüyorum ve yorumlara
/*(1)*/ (yaptığım) olarak başvurabilirim, böylece bu bir sonraki çalışan için kolayca izlenebilir (ve o da hemen gerekli olan parçaları bulmayı başardı) ve sonra herhangi biri spesifikasyonun ne olduğunu bilmek isterse yorumu yukarıdan okuyabilir ve eğer biri sahte kodun ne olduğunu bilmek isterse ve eğer birisi sahte kodu koda dönüştürmek isterse işte oraya gidersiniz. Benim için bu, orijinal talebi koruduğu (e-postadan kesildi) ve düşünce treninin çok fazla düşünmeden hızlı bir şekilde toplanmasına izin verdiğinden ve kolay dönüşümlerin kullanılmasına izin verdiği için çok daha okunabilir (benim durumum için). gerçek kod içine sözde.
Ve evet, sözde ve böyle sözde kodda beklendiği gibi çalışmadığını söyleyen bazı satır içi yorumlar var, çünkü gereksinim verilerle tam olarak eşleşmedi, bu yüzden verileri Tweak yapmamız gerekiyordu. Ama bu benim açımdan. Edge vakalarını satır içinde belgeledik ve sahte kodu mantığı takip etmek için uygun kodda bıraktık, böylece orijinal gereksinimlerden ne beklendiğini biliyorduk