Kodda yorum yapmaktan hoşlanmayan bir ekip üyesi ile nasıl baş edebilirim?

Ekip üyelerimden biri kodunda yorum yapmaktan kaçınıyor.

Kodu kendiliğinden belgelenmiyor ve diğer programcılar kodunu anlamakta zorlanıyorlar.

Ondan kodunu yorumlamasını birkaç kez istedim, ancak daha sonra yapacağına dair mazeret veya iddialarda bulundu. Kaygısı, yorum eklemek çok zaman alacak ve projeleri geciktirecek.

Kurallarını doğru bir şekilde belgelemeye ikna etmesi için kendisine hangi argümanı sunabilirim?

Bu notta, kod yorumlarına odaklanmak yanlış mıyım yoksa bu, ele alınması gereken daha büyük bir sorunun göstergesi mi?

Yalnızca yorumlar daha iyi kod için yapılmaz ve yalnızca "daha fazla yorum" için bastırmanın, /* increment i by 1 */stil yorumlarından biraz daha fazlasını vermesi olasıdır .

Öyleyse kendinize bu yorumları neden istediğinizi sorun . “En iyi uygulama”, nedenini anlamadığınız sürece bir argüman sayılmaz.

Şimdi, yorum kullanmanın en çarpıcı nedeni, kodun anlaşılmasının daha kolay olması ve insanların yorum eksikliğinden şikayet etmeleri durumunda, ya ipucu olmayan papağanlar ya da çalıştıkları kodu anlamakta zorlanıyorlar.

Bu yüzden eksik yorumlardan şikayet etmeyin: okunamayan kodlardan şikayetçi olun. Ya da daha iyisi, şikayet etme, sadece kod hakkında sorular sormaya devam et. Anlamadığınız bir şey için, yazan kişiye sorun. Yine de bunu yapmalısın; okunamayan kod ile daha fazla soru soracaksınız. Ve daha sonra bir kod parçasına geri dönerseniz ve ne yaptığını doğru hatırladığınızdan emin değilseniz, aynı soruyu tekrar sorun.

Yorumlar düzeltebilirse ve meslektaşınızın işleyen bir beyni varsa, bir noktada kodu yorumlamanın size her zaman aptal sorular sormaktan çok daha kolay olduğunu fark edecektir. Ve soruları bulamıyorsanız, o zaman belki bu kod zaten mükemmel bir şekilde okunabilir durumdadır, ve hatalı olan sizsiniz - sonuçta, tüm kodların yorumlara ihtiyacı yoktur.

İnsanların becerileri cephesinde, küçümseyici ses kullanmaktan kaçınmak veya her ne pahasına suçlamaktan kaçının; Sorularınız konusunda ciddi ve dürüst olun.

Kendini belgeleyen kod yazarken ya da faydalı yorumlar yazmakta zorlanan birçok geliştiriciyle tanıştım. Bu tür insanlar çoğu zaman bunu doğru yapmak için yeterli öz disiplin veya deneyimden yoksundur.

Asla işe yaramaz olan, "daha fazla yorum eklemelerini söylemek". Bu, kendi disiplinlerini veya deneyimlerini artırmayacaktır. IMHO işe yarayabilecek tek şey sık sık kod incelemeleri yapmak ve yeniden düzenleme oturumları yapmaktır. Bir dev bir görevi tamamladığında, anlamadığınız kodun herhangi bir bölümünü açıklamasına izin verin. Derhal, her ikiniz de 6 ay sonra anlayacağınız şekilde kodu yeniden gözden geçirin veya belgeleyin.

Bunu birkaç ay boyunca, haftada en az iki kez yapın. Yeterince şanslıysanız, diğer geliştiriciler bu oturumlardan öğrenerek inceleme sıklığını azaltabilir.

Henüz kimsenin kod incelemelerinden bahsetmediğinden şaşırdım. Kod değerlendirmeleri yapın! Kötü kaliteyi kontrol ettiğinde, sadece "yorum ekle" deme. Sürekli olarak sorular sorun ve kodunun ne yaptığını ve nedenini size söylemesini sağlayın. Not almak. Daha sonra, kod incelemesinin sonunda, notların bir kopyasını verin ve sorularınızı oldukça net bir şekilde ortaya koymasını söyleyin. Ya daha fazla yorum yaparak ya da sadece daha iyi kaliteyi sağlamak için kodunu yeniden gözden geçirerek (tercihen mümkün olduğunda ikinci)

Bu, takım çalışanınızın ürettiği koda bağlıdır. Eğer okursanız Temiz Kod Amca Bob kitabı sen o aslında tercih olduğunu göreceksiniz değil koduna yorum eklemek. Eğer kodun kendisi olması gerektiği gibi okunursa, yorum yapmak için herhangi bir ihtiyaç yoktur.

Durum böyle değilse veya pazarlık yapılmayan politikalardan dolayı yorum yapmanız gerekiyorsa, asıl soru, yorum yazmasını isteyen yalnızca siz mi, yoksa tüm takım mı yoksa takım / proje mi olduğu sorusudur. Önder. Eğer sadece sizseniz, neden bu kadar önemli olmadığını anlamak için diğer meslektaşlarınızla konuşmalısınız.

Proje liderinin yorumları eksikse, bunların eksiksizliğini bir parçası olarak da isteyebilirsiniz , yani gönderilen kodda yorum yoksa, çalışma henüz bitmedi. Mevcut işi bitinceye ve bu yorumlar için gerekli olana kadar başka işler yapmaya devam edemeyebilir. Ancak, bu tür bir zorlamanın büyük olasılıkla korkunç yorumlara yol açacağını aklınızda bulundurun (kodsuz yorumların tekrarlanmasını bekleyin).

Alçakgönüllü görüşüme göre tek uygulanabilir yöntem, sizin ve diğer herkesin yorumlardan elde ettiği gerçek kazancı tartışmaktır. Bunu sadece tartışma yoluyla anlamıyorsa, her zaman da zor yol vardır: yeni kod yazmalarına izin vermek yerine, mevcut kod üzerinde çalışmalarını sağlamak. Mümkünse, bunlara iki farklı çalışma alanı bulmalısınız - biri uygun faydalı yorumlar ile diğeri yorumlar içermez. Başkasının okunamayan ve yorumlanamayan kodunu okumak zorunda olmak, kendi çalışmanız için bir göz açıcıdır.

Hepimiz bir zamanlar oradaydık ve özensiz çalışmak için bir kaynağın orijinal yazarına kızdık. Her birimizin aynı zamanda okuryazarlığı önemsemeniz gerektiğini fark etmenizi sağlayan bir yazar olduğu ek bir yansımasıdır - bu nedenle, bu yansıması teşvik etmek için sonuçları meslektaşınızla tartışmayı unutmayın.

Talimatları takip edemeyen bir çalışanınız varsa, onu işten çıkarın ve kariyerinin ilerlemesine yardımcı olmayacağının kesin olduğundan emin olun. Kodlama tarzındaki tutarlılık bir ekip için kritik öneme sahiptir ve eğer herkes yorum yazıyorsa ve bu değilse, kodlama stiline zarar verir.

Bu, muhtemelen ona yardım edebileceğini söyledi. Tecrübelerime göre, biri yorum yapmanın çok zaman aldığını protesto ettiğinde , psikolojik bir engel var ...

1. Kod / tasarım seçimleri konusunda bilinçli ve onları nesirlendirmek istemiyor. (Kod incelemeleri, birisinin kendi güvenini arttırmak ve onları yıkmak kadar faydalı olabilir.)
2. Çok doğrusal çalışıyor ve ileride pek düşünmüyor. Yorum yapmak acı vericidir çünkü niyetini farklı bir şekilde oluşturmak için yazmak üzere olduğu ani kodu çalışma hafızasından çıkarmaya zorlar. (Bu doğruysa, yorum yapmak kod kalitesi için çok önemlidir.)
3. Tarihsel olarak insanlar yorumlarını anlamıyor.

Bir programcının, yorumların testler gibi olduğunun farkına varması önemlidir: Sadece gelecekteki kullanımlar için değildirler - Programcının kendisi içindir. Yaklaşımı hakkında farklı düşünmeye zorlarlar.

Bunların hiçbiri CI, testler veya kod incelemelerinin yerine geçmez. Kodlamanın kendisi değil, kod yazmanın çok kritik bölümlerinden sadece bir tanesi.

Kod inceleme yazılımını edinin ve iyi kullanın.

Fırın kullanıyoruz ve seviyoruz. Her değişikliğin gözden geçirilmesi gerektiğine dair bir politikamız var (geliştiricilerin etiketler ve çatışmasız birleşmelerde kendileri için incelemeleri artırmalarına / onaylamalarına izin vermemize rağmen (çoğumuz rebaseif kullanıyor olsak da);

Açık olmayan kod, kod incelemesinin reddedilmesinin nedenidir. Düzeltmenin yorum veya daha açık kod olması önemli değil, ancak gözden geçirenin anlayabilmesi gerekir. Bazı geliştiriciler kodu yeniden yazmayı tercih eder, ancak bazıları (kendim dahil) yorumlarda niyetini ifade etmeyi genellikle daha kolay bulur (kod ne yaptığını kolayca gösterebilir, ancak ne yapması gerektiğini göstermek daha zordur ).

Kodun netliği hakkında herhangi bir soru varsa, gözden geçiren her zaman kazanır. Tabii ki yazar anlıyor, çünkü yazmışlar. Başka birine açık olması gerekiyor.

Kiln gibi bir yazılım kullanarak, hiçbir değişiklik gözden kaçırılmaz. Dev ekibimdeki herkes bu yolu çok tercih ediyor. Kod inceleme yazılımı hem kod kalitemiz hem de uygulama kalitemiz üzerinde büyük bir etkiye sahiptir :-)

Devs’in yazılımı ilk tanıtırken reddedilen incelemelerle savunması kolaydır, ancak benim deneyimime göre, işlerin bu şekilde daha iyi olduğunu farketmeleri ve benimsemeleri çok uzun sürmez :-)

Düzenleme: Ayrıca kayda değer, devs’in şifreli kodları sözlü olarak veya derlemede yapılan açıklamalarda açıklamamalarını sağlarız. Bir şey net değilse, açıklamak için en iyi yer koddadır (yorumlarda veya yeniden gözden geçirme yoluyla), sonra yeni değişiklik kümelerini aynı incelemeye ekleyin.

İlginçtir ki , doğal dile uygulanan okunabilirlik , okuma ve anlama hızı ile ölçülür. Sanırım basit bir kural gerçekten de kabul edilebilir, eğer belirli bir kod yorumu bu özelliği iyileştirmezse, bundan kaçınılabilir .

Neden yorumlar?

Kod yorumu gömülü bir dokümantasyon biçimi olsa da, dilin kendi öğelerini kullanarak gereksiz "fazla belgelenmiş" programlamayı (anlamlı koddan) önlemek için üst düzey programlama dillerinde birçok yol vardır. Ayrıca, bireysel ifadelerin kelimenin tam anlamıyla tautolojik bir biçimde açıklandığı (zaten verilen cevaplarda "/ * 1 * /" i örneklendiğinde, "/ * 1 * /" örneğine dikkat edin), programlama kitapçığından kodu listelemeye dönüştürmek kötü bir fikirdir. sadece dili ile deneyimsiz programcılar için.

Bununla birlikte, gerçekte “tüm kötülüklerin kaynağı” olan “az belgelenmiş” (ancak anlamsız) kodu yorumlamaya çalışmaktır. "Belgelenmemiş" kodun varlığı çok kötü bir sinyaldir - ya yapılandırılmamış bir karışıklık ya da mistik kaybedilen amaçların tuhaf kesilmesidir. Açıkçası, böyle bir kodun değeri en azından sorgulanabilir. Ne yazık ki, her zaman örnekler vardır, gerçekten de, (görsel olarak gruplandırılmış) biçimlendirilmiş kod satırlarının bir bölümüne, yeni alt yordamın içine kaydırmak yerine, ("küçük kafanın hobgobini" olan "aptalca tutarlılığı" dikkate alın) bir bölüme yorum eklemek gerçekten daha iyi olduğunda, her zaman örnekler vardır. .

Kod okunabilirliği! = Kod yorumları

Okunabilir kod, yorumlarda açıklama gerektirmez. Koddaki her belirli yerde, her zaman bu belirli kodun gerçekleştirmesi gereken bir görev bağlamı vardır. Amaç eksikse ve / veya kod gizemli bir şey yaparsa = ne pahasına olursa olsun kaçının. Garip bilgisayar korsanlarının kodunuzu doldurmasına izin vermeyin; bu, temel teknolojilerin anlaşılması için buggy teknolojilerinin zaman / ilgi eksikliği ile birleştirilmesinin doğrudan bir sonucudur. Projenizde mistik kodlardan kaçının!

Öte yandan, Okunabilir program = kod + belgeler , örneğin "API'ye yorum" belgelerinin oluşturulmasını kolaylaştırmak için birden fazla meşru yorum bölümü içerebilir.

Kod stili standartlarını takip edin

Yeterince komik olan soru, kodun neden yorumlanacağıyla ilgili değil, ekip çalışmasıyla ilgili - yüksek düzeyde senkronize edilmiş bir tarzda kodun nasıl üretileceği (herkesin okuyabileceği / anlayabileceği) ile ilgili. Şirketinizde kod tarzı standartlarına uyuyor musunuz? Asıl amacı, yeniden düzenleme gerektiren kod yazmaktan kaçınmak, fazla "kişisel" ve "öznel" olarak belirsiz olmaktır. Bu yüzden, eğer birinin kod stilini kullanma zorunluluğunu görürse, uygun şekilde nasıl uygulanacağına dair çok ciddi araçlar var - insanları eğitmekle başlayıp kodun kalite kontrolü için otomasyonla (sayısız metin vb.) Ve (revizyonu bitirmek) kontrolü entegre) kod inceleme sistemleri.

Bir kod okunabilirliği evangelisti ol

Bu kodun yazıldığından daha sık okunmasını kabul ediyorsanız. Fikirlerin açık bir şekilde ifade edilmesi ve açıkça düşünülmesi sizin için önemliyse, hangi dilin iletişim için kullanıldığına bakılmaksızın (matematik, makine kodu veya eski ingilizce) .. Göreviniz alternatif ve çirkin alternatif düşünme biçimini ortadan kaldırmaksa .. (üzgünüm , sonuncusu başka bir "tezahür" den ..) .. soru sor, tartışma başlat, belirsizliği ele alan (muhtemelen sadece Beck'in tasarım modellerine benzer bir şey değil, daha çok RC Martin tarafından daha önce bahsedildiği gibi) kod temizliği üzerine kitaplar düşündürmeye başla. programlamada. Ayrıca, ana fikirlerin bir mermi noktası geçişi (okunaklılık konusunda O'Reilly kitabından alıntı)

• Her kod satırı için geçerli olan ipuçlarıyla adlandırma, yorum yapma ve biçimlendirme işlemlerini basitleştirin
• Karmaşıklığı ve karışıklığı azaltmak için programınızın döngülerini, mantığını ve değişkenlerini iyileştirin
• Her seferinde bir işi yapmak için kod bloklarını yeniden düzenleme gibi işlev düzeyindeki sorunlara saldırı
• Okunaklı olmasının yanı sıra kapsamlı ve özlü bir test kodu yazın

"Yorum yapma" yı kesmek, hala çok şey bırakılmış (Sanırım yorum gerektirmeyen bir kod yazmak harika bir egzersiz!). Anlamsal olarak anlamlı tanımlayıcıları adlandırmak iyi bir başlangıçtır. Daha sonra, mantıksal olarak bağlı işlemleri fonksiyonlar ve sınıflar halinde gruplayarak kodunuzu yapılandırın. Ve bunun gibi. Daha iyi bir programcı daha iyi bir yazardır (elbette verilen diğer teknik becerileri varsayarsak).

Kod yorumlarına odaklanmak yanlış mıyım yoksa bu çözülmesi gereken daha büyük bir sorunun göstergesi mi?

Biraz. Harika kod yorumlara ihtiyaç duymuyor. Ancak dediğiniz gibi, kodu kendiliğinden belgelenmiyor. Bu yüzden yorumlara odaklanmam. Geliştiricilerinizin beceri ve işçiliğini geliştirmeye odaklanmalısınız.

Peki bunu nasıl? Doc Brown'ın gözden geçirme / yeniden düzenleme oturumları ile ilgili önerileri iyi bir fikirdir. Çift programlamayı daha etkili buluyorum, ancak uygulanması daha da zor olabilir.

Öncelikle, yorumlar hakkındaki yaklaşımınızı tekrar ele almanızı öneririm.

API düzeyinde dokümantasyon yorumları yapıyorlarsa (daha sonra halka açık), bu geliştirici işini yapmıyordur. Ancak diğer tüm yorumlar için dikkatli olun.

Karşılaştığım vakaların çoğunda, yorumlar kötüdür. Nedenini iyi anlayabilmek için Robert Martin tarafından "Temiz kod" adlı kod yorumları bölümünü okumanızı tavsiye ederim .

Yorumlar kodunuzu çeşitli şekillerde incitti:

1) Bakımı zordur. Refactoring yaparken ekstra iş yapmanız gerekecek; Yorumda açıklanan mantığı değiştirirseniz, yorumu da düzenlemeniz gerekir.

2) Genellikle yalan söylerler. Yorumlara güvenemezsiniz ve bunun yerine kodu okumalısınız. Hangisi soruyu gündeme getiriyor: neden yorumlara hiç ihtiyaç duyuyorsun?

// this method returns the sum of 'a' and 'b'
public int GetHash(int a, int b)
{
    //the calculation of the hash
    int result = a*b;
}

(Karma toplam değil üründür.)

3) Yorumlar kodu bozar ve çok nadiren herhangi bir değer ekler.

Benim çözümüm: Daha fazla yorum eklemek yerine, onlardan kurtulmaya çalışın!

Bir takım üyesi başka bir takım üyesinin kodunu anlamakta zorlanıyorsa (herhangi bir nedenle); Daha sonra bu ekip üyesi orijinal kodu kimin yazdığını (herhangi bir kontrol revizyonu sistemi) kim bulabilir ve bu kodun yazarından doğrudan açıklamasını istemek için teşvik edilmelidir (örneğin, masalarına doğru yürüyün, oturun ve tartışın).

Bu durumda yorum eksikliği bir sorunsa, kodunu yeterince yorumlamayan kişi ne yaptığını açıklamak için zamanının büyük kısmını harcayacaktır; ve (eğer akıllılarsa) tüm bu açıklamalara zaman harcamaktan kaçınmak için yorumlar eklemeye başlayacaktır.

Ekip üyelerini birbirlerinden açıklama istemelerini teşvik etmenin başka nedenlerden dolayı değerli olduğunu unutmayın. Örneğin, belki bir ekip üyesi daha az deneyimlidir ve daha deneyimli ekip üyelerinden bir şeyler öğrenebilir.

Çoğunlukla, ekip üyelerini birbirlerinden açıklama istemelerini teşvik ederek kendi kendini dengeleyen bir sistem yaratırsınız; farklı ekip üyeleri birbirlerine "otomatik olarak ayarlanır".

Bu büyük ölçüde tdammers cevabının bir uzantısıdır, ancak düzenli aralıklarla kod incelemeleri yapar.

Ona (ve diğer geliştiricilere) oturmak, kodlarını yürümek ve üstlerinin ve meslektaşlarının önünde az ya da çok savunmak, herkesi daha iyi kodlayıcılar yapacak ve nispeten kısa bir süre boyunca gerçek bir değer katacaktır. Kısa vadede, söz konusu geliştiriciye inceleme sırasında kodunu doğru şekilde yorumlayabilmesi için hiçbir mazeret vermeyecektir.

DÜZENLEME: Birisinin önerimi neden reddettiğinden emin değilim - belki de kod incelemesinin yararlarının ortak bilgi olacağını kabul ettim ... lütfen uygulamanın topluluk analizi için bu konuyu inceleyin:

Kod incelemesi iyi bir uygulama mıdır?

Yorum yapma konusundaki sık sık aşırı görüşleri göz önünde bulundurursak, tartmak için tereddüt ediyorum.

Düzgün belgelenmesi gerektiğini (okunamayan) bir kod yazacaksanız size sunabileceğim bazı argümanlar nelerdir?

Sürdürülebilir ve okunabilir bir kodun nasıl yazıldığını anlamak zaman, uygulama ve tecrübe gerektirir. Deneyimsiz programcılar (ve ne yazık ki pek çok deneyimli olanlar) genellikle Ikea Etkisi'nden ( PDF ) muzdariptir . Bunun nedeni, onu oluşturdukları ve yakından tanıdıkları ve kodun yalnızca harika değil aynı zamanda okunabilir olduğundan da emin olmalarıdır.

Eğer kişi harika bir programcıysa, herhangi bir dokümantasyon gerekli ise çok az. Ancak, çoğu programcı harika değildir ve kodlarının çoğu "okunabilirlik" bölümünde acı çekecektir. Vasat ya da programcıdan “kodlarını açıklamasını” istemek, kodlarını daha kritik bir gözle görmeye zorlamaları açısından faydalıdır.

Bu, kodlarını "belgelemek" anlamına mı geliyor? Şart değil. Durumda, geçmişte bu konuda benzer bir programcı vardı. Onu belgelemeye zorladım. Maalesef belgeleri onun kodu kadar çözülemezdi ve hiçbir şey eklemedi. Retrospect kodunda incelemeler daha yararlı olurdu.

Siz (veya bir delege) bu programlayıcıya oturmalı ve eski kodlarından bazılarını kaldırmalısınız. Sadece üzerinde çalıştığı yeni şeyler değil. Asgari etkileşim ile kodunda size rehberlik etmesini istemeniz gerekir. Bu ayrıca kodunu yazarken açıklayacağı ayrı bir "belgeleme" oturumu olabilir. O zaman daha iyi yaklaşımlar hakkında geri bildirim almalıdır.

Bir kenara ... kodun "okunabilirliğinin" ne kadar iyi olduğuna bakılmaksızın bazen bazı belgelere ihtiyaç duyulur. API'ler belgelere sahip olmalı, son derece teknik ve karmaşık işlemler programlayıcıya dahil olan süreçleri anlamada yardımcı olacak belgelere sahip olmalıdır (genellikle programcıların bilgi alanı dışındadır) ve karmaşık regex'leri gibi bazı şeyler gerçekten neye karşı olduğunuzu belgelemelidir.

Pek çok proje kod belgelerine ihtiyaç duyar: arayüz belgesi, tasarım belgesi, ...

Bazı projeler, bu dokümantasyonun kod açıklamalarına koyulmasını ve Doxygen veya Sphinx veya Javadoc gibi araçlarla çıkarılmasını gerektirir, böylece kod ve dokümantasyon daha tutarlı olur.

Bu şekilde, geliştiricilerin kod üzerine faydalı yorumlar yazmaları gerekir ve bu görev proje planlamasına dahil edilir.

Cevapların ve yorumların çoğunun neye işaret ettiğini belirteceğim: Muhtemelen burada algılanan çözümünüzü zorlamak yerine asıl konuyu çözmeniz gerekir.

Kodunda yorumları görmek için motive oldunuz; neden ? Bir sebep verdin; bu neden senin için neden bu kadar önemli? Onun yerine başka bir şey yapması için motive oluyor; neden ? Bir sebep verecek; neden bu sebep onun için bu kadar önemli? Çatışmanın gerçekten ortaya çıktığı seviyeye gelinceye kadar bunu tekrarlayın ve orada ikinizin de yaşayabileceği bir çözüm bulmaya çalışın. Bahse girerim yorum yapmakla çok az ilgisi var.

İyi bir kodlama standardını izlerseniz, gereken minimum yorum sayısı olacaktır. adlandırma kuralları önemlidir. Yöntem isimleri ve değişken isimleri rollerini tanımlamalıdır.

TL’m daha az yorum kullanmamı önerir. kodumun anlaşılabilir ve kendi kendini tanımlayıcı olması gerektiğini istiyor. simple example: arama düzeni için kullanılan dize türü için değişken ad

   var str1:String="" //not uderstandable
   var strSearchPattern:String="" //uderstandable

Kod incelemesi yanıtlarını seviyorum, ancak belki de işlemim de size yardımcı olacaktır.

Yorumlara bayılırım, ancak ilk seferde neredeyse hiç bir zaman onları koda eklemiyorum. Belki bu sadece benim tarzımdır ancak geliştirme sırasında kodun aynı kısmına 3-5 kez vuracağım (yeniden düzenleme, yazma testleri vb.).

Ne zaman kafam biraz karıştığında veya ne zaman birisi bana kodun bir bölümü hakkında bir soru sorduğunda, bunu düzeltmeye çalışıyorum, bu da mantıklı geliyor.

Bu, kafa karıştırıcı bir işlem kümesini kendi işlevlerine kaldırmak için bir yorum eklemek kadar basit olabilir veya yeni bir nesneyi çıkarmak gibi daha büyük bir yeniden düzenleyiciyi tetikleyebilir.

Gruptaki herkesi kodlarının başkalarına okunabilir olduğunu "kendilerine" "teşvik etmenizi öneririm - bu, birileri size kodunuz hakkında her soru sorduğunda, bir değişiklik yapmayı taahhüt ettiğiniz anlamına gelir - veya daha iyisi o zaman değişikliği yapmak için kişi!

Bunun için "Takım Sözleşmenizin" bir parçası olarak itmeyi ciddiye alın (Bir tane yoksa kesinlikle kesin bir sözleşme oluşturun) - bu şekilde herkes bu konuda hemfikir ve böyle bir yerde bir duvarın üzerine oturtun. Yapmaya karar verdikleriyle ilgili herhangi bir soru.

Belki de bu adama iyi kodlama disiplini hakkında bir takdir verilmesi gerekiyor ve neden diğer kişilerin yazdığı kodu anlayabilmesi önemli.

Kariyerimde gerçekten çok kötü bazı kod tabanları üzerinde çalıştım, kodun çok kötü organize edildiği, değişken isimleri çok zayıf, yorumlar o kadar kötü ya da varolmayan, kod temeli üretkenliğime zarar verdi. Anlamadığınız bir kod tabanını düzeltmek veya geliştirmek için çalışamazsınız ve yeni gelenler için uygun olmayacak şekilde yazılmışsa, üzerinde çalışmaktan daha fazla zaman harcarlar.

Zorlu tecrübeden daha iyi bir öğretmen olamaz!

Her kod tabanında, gizlenen bazı bitler var, sistemin parçaları kimseye dokunmak istemiyor çünkü bir şeyleri kırmaktan korkuyorlar ya da herhangi bir anlamlı iş yapamıyorlar çünkü kodunu kim yazdıysa ve anlayışı ele geçirdi mi? onlarla kodun. Eğer bu kod açıklanmadıysa ve kendi kendini belgelendirmiyorsa, o zaman işleri daha da kötüleştirir.

Sana kod kodunuzun bitini bulmanızı ve bunun için zahmetli kodlayıcı sorumluluğunu vermenizi öneririm. Ona sahipliğini ver, sorumluluğunu üstlen, kod üzerinde çalışmanın gerçek acısını öğrenmesine izin ver, çünkü kısa bir zaman diliminde anlaşılması iyi belgelenmemiş veya imkansız değildir. Birkaç ay çalıştıktan sonra, gelmeye başlayacağına eminim.

Yorum yapmadan ona bir tane kod daha verin ve kodu anlamasını isteyin. O zaman doğru yorumların önemini anlayabilir.

Bu programcı bazı kod bakımı yapıyor mu. Değilse, şunları yapmalıdır: Etrafınızdaki sevilmeyen herhangi bir projeyi kontrol etmeli ve bakımını ona vermelidir.

Genellikle bunlar, düzeltilmesi kolay olanı düzeltmek için neler olup bittiğini anlamaya çalışırken saat kaybettiğiniz, kötü belgelenmiş projelerdir. Bu tür bir deneyim onu ​​güncel istemezse, doğru ve yararlı belgeler hiçbir şey yapmaz.

Geçmiş projelerimden birinde düzinelerce yorum eksikti (algoritma, sonuçlar ya da bazı temel JavaDoc), bu yüzden onun için 130 sayı yapmaya karar verdim, her 4 günde bir sayı hakkında e-posta bildirimi yaptım. 3 hafta sonra 280 sorun yaşadı, daha sonra yorum yazmaya karar verdi.

Yorumların bir amacı ve yalnızca bir amacı vardır:

Bu kod neden bu şeyi yapıyor?

Bir yorum neden bir şeylerin böyle olduğunu açıklamıyorsa, kaldırılmalıdır. Kodu bozan işe yaramaz yorumlar işe yaramazdan azdır, aktif olarak zararlıdır.

IDE'mdeki yorumlarımı en belirgin şey haline getirme alışkanlığım var. Yeşil bir arka plan üzerinde beyaz metin ile vurgulanırlar. Gerçekten dikkatini çek.

Bunun nedeni, kodun bir şeyin ne yaptığını açıklamasıdır ve yorumların neden yaptığı içindir. Bunu yeterince vurgulayamıyorum.

İyi bir yorum örneği:

/* Must instantiate clsUser before trying to encrypt a password because the code to 
   encrypt passwords only uses strong encryption if that module is loaded. */

Kötü bir örnek:

/* instantiate clsUser */

Yorumları kodun "bölümleri" olarak kullanıyorsanız: Mamut yönteminizi daha küçük, kullanışlı adlandırılmış işlevlere bölün ve yorumları kaldırın.

Bir sonraki satırda ne yaptığınızı söylüyorsanız: Kodu kendinden açıklamalı hale getirin ve yorumu kaldırın.

Yorumları uyarı mesajı olarak kullanıyorsanız: Nedenini söylediğinizden emin olun.

Buradaki cevapları tamamlamak için şunu ekleyebilirim: "Doğru yapılmasını istiyorsan kendin yapmalısın."

"Baş kod yorumcusu" olmak istemem, bu geliştiricinin ne yapmasını istediğinizi göstermede rol model olmak demek. Göstermenin söylemekten daha etkili olduğunu söylüyorlar . Kalite yorumlarının yararını gösterebilir veya hatta bu diğer geliştiriciyi (hatta istediği ölçüde) mentorluk ederseniz, kod yorumunu kabul etmede daha fazla başarı elde edebilirsiniz.

Benzer şekilde, evde yapmak istemediğim bazı ev işleri var. Ancak aynı işleri, karımın "evcil hayvan peeve" işleri olarak gerçekleşir ... onun mutlu olması için yapılması gereken işleri . Aynı durum tersi için de geçerlidir. Bu geliştiricinin sizden farklı öncelikleri olduğunu kabul etmeniz gerekebileceğini ve her konuda sizinle aynı fikirde olmayacağınızı düşünüyorum. Karım ve benim bulduğumuz çözüm, "evcil hayvan peeve" işleri için, kendi başımıza biraz daha fazla iş yapmak anlamına gelse de, onları kendimiz yapmak zorundayız.

Basit: Çalışan yorum yapmıyorsa shift+alt+j, her bir yöntemde aynı anda kod girerek otomatik yorum yapmasını isteyin . Bu sorunlardan kaçınmak için lütfen kod revizyonunu yapın.