Yüksek Ciro Ortamlarında Daha Fazla Yorum Daha mı İyi?

Bugün bir meslektaşımla konuşuyordum. İki farklı proje için kod üzerinde çalışıyoruz. Benim durumumda, kodum üzerinde çalışan tek kişi benim; Onun durumunda, düzenli olarak (8-12 ayda bir) gelip giden co-op öğrencileri de dahil olmak üzere, aynı kod tabanında birden fazla kişi çalışır. Yorumlarıyla liberal olduğunu ve her yere koyduğunu söyledi. Onun mantığı, kodun büyük bir kısmı onun tarafından yazılmadığı ve onun dışında biri tarafından değiştirilebildiği için, şeylerin nerede olduğunu ve ne yaptığını hatırlamasına yardımcı olmasıdır. Bu arada, kodumdaki yorumları en aza indirmeye çalışıyorum, onları sadece açık bir geçici çözüm veya hata olan yerlere yerleştiriyorum. Ancak, kodumu genel olarak daha iyi anladım ve üzerinde daha doğrudan kontrol var.

Bu yorumlardaki düşüncem minimal olmalı ve kod hikayenin çoğunu anlatmalı, ancak mantığı da mantıklı. Akıl yürütmesinde herhangi bir kusur var mı? Kodu karıştırabilir, ancak kısa ve orta vadede üzerinde çalışan birçok kişi varsa sonuçta oldukça yararlı olabilir.

Yorumlar kodu karıştırmaz.

Ve yaptıklarında, her yarım iyi IDE yorumları gizleyebilir / katlayabilir. İdeal olarak, öykü yorumlarınızla değil, kodunuzla, gereksinimler belgenizle, taahhüt geçmişinizle ve birim testlerinizle anlatılmalıdır. Bununla birlikte, aşırı yorum yapmak ancak yorumlar neden ve nasıl değil üzerinde yoğunlaştığında zarar verebilir, ancak bu farklı bir tartışmadır .

Bence hem siz hem de iş arkadaşınız "haklı "sınız, fark, elbette, tek başına çalışmanız ve genellikle deneyimsiz geliştiricileri içeren bir ekipte olması. Yorumlarda çok farklı bir felsefeniz yok, ancak kodunuzu iletme konusunda çok farklı gereksinimler var. “Hatırlamama yardımcı oluyor” argümanı, sizden çok daha fazla kodla uğraşması ve daha da önemlisi, her biri kendi kişisel tercihleri ​​ve tuhaflıkları olan farklı insanlar tarafından üretilen kodlardan kaynaklanıyor olabilir.

Günün sonunda, kod yorumları, açık kusurları da olsa, kodunuzu iletmenin en basit ve en hızlı yoludur. Takım kompozisyonuna ve organizasyonuna bağlı olarak, en düşük ortak payda için geçerli olan tek yol bile olabilir. Kendimi genellikle yalnız çalıştığında ve özellikle dengesiz bir takım becerisi akıllıca ise, bir ekipte çalışırken meslektaşınıza uyum sağlayarak yorum felsefenizi takip ederken bulurum.

Bu tür ortamlardaki üretken yorumlar, başka bir şekilde çözülmesi gereken bir sorunu örtüyor.

Kalite, okunabilir kod, ne yaptığını açıklamak için asla ek yorumlara ihtiyaç duymamalıdır. Yorum yapmanın tek zamanı, bir şeyin neden belirli bir şekilde yapıldığını açıklamak istediğiniz zamandır. Ve o zaman bile, bu yorumlar tartışmalı olarak kaynak kontrolü taahhüt mesajlarında olabilir.

Çözdüğü sorun, kodlarını okunabilir bir şekilde nasıl yazacağını bilmeyen öğrencilerle çalışmak zorunda olması. Kanımca, kodun yorumlarla karıştırılması bu soruna zayıf bir çözümdür.

Sıkı kod incelemeleri, aynı şirkette veya başka bir yerde olsun, hem kodu düzenli tutmak hem de bu öğrencileri geleceğe geliştirmek için çok daha etkili olacaktır.

Yorumlarla ilgili sorun, kodla gerçekten hızlı bir şekilde senkronize olmama eğilimindedir. Bu, kodda genellikle yanıltıcı veya yanlış yorumlar olduğu anlamına gelir, bu nedenle okunabilirliğe yardımcı olduklarından daha fazla zarar verirler.

Amaç, bir kod tabanının anlaşılmasını ve değiştirilmesini kolaylaştırmaktır. Bunu yorumların liberal kullanımı ile yapabilirsiniz (veri yorumlarının dışında sorunla karşılaşabilirsiniz) veya kendi kendini belgeleyen kod yazabilirsiniz (mümkün olduğunca) ve yalnızca önemsiz olmayanları açıklamak için yorumları kullanabilirsiniz. sorular. Her iki yaklaşım da işe yarayabilir, ancak kodu değiştirmek için sadece yorumları değil, kodun kendisini anlamanız gerekir. Bu nedenle, yorumlar kodu anlamanıza yardımcı olsa da, günün sonunda yine de kodun kendisini anlamanız gerekir. Bununla birlikte, kendi kendini belgeleyen kod yaklaşımını tercih ederim. Temiz bir kod tabanı oluşturmak için daha doğrudan bir yol gibi görünüyor.

"Yüksek Cirolu Ortamlarda Daha Fazla Yorum Daha mı İyi?"

Bence daha kötü olabilirler:

• Farklı yazarlar farklı stiller ve ayrıntı seviyeleri kullanacak ve diğer insanlar tarafından yapılan yorumları güncelleme konusunda daha az olacaktır.

• "Neyin yorumlanması gerekiyor" düşüncesi kişiden kişiye değişir.

• Açıklayıcı adlarla okunması kolay kodun aksine açıklamak için yorumlarla okunması zor olan kod yazma pratiğine devam ederler.

• Biçimlerini ve tutarlılığını sürdürmek kendi başına bir iş haline gelir.

• Yeni kullanıcılar, hızlı değişiklikler yapmadan önce 'format' standardını öğrenmek zorundadır.

Nokta 1: Yüksek ciro ortamlarında netlik önemlidir

Nokta 2: Ayrıntı, Netlik Değildir

Kodunuza yorum eklemek netliği artırabilir veya etmeyebilir; eklediğiniz yorumlara bağlıdır. Ve en iyi netliğe ulaşıldığında, ek yorumlar durumu daha da kötüleştirir, daha iyi yapmaz.

Yorumlar netliğin bir bileşeni olsa da, kod kalitesi çok daha önemli bir bileşendir. Akıllılık, netliğin tam tersidir . Kodun işlevi sıradan bir okuma ile hemen görülmezse, kod özellikle net değildir ve yorumlar (yorumların kalitesi ne olursa olsun), açık kodun zayıf ve etkisiz bir alternatifidir.

Örneğin, ilgisiz bir alanın yüksek bitine bir bayrak doldurmak belirli durumlarda mükemmel bir şekilde izin verilebilir ve belirli durumlarda performans açısından bir anlam ifade edebilir, ancak netlik açısından her zaman kötü bir fikirdir. , cehennemden bahsetmiş olsan bile.

Kodunuzun ne yaptığını açıklamak zorunda olduğunuzu fark ederseniz, aşağıdakilerden birini göz önünde bulundurun: Bunlardan bazılarının performansı etkileyebileceğini unutmayın, ancak performans bazı durumlarda netlik kadar önemli olmayabilir.

• Daha iyi değişken adları ve işlev adları
• Daha iyi kod düzeni ve aralığı
• İyi bir fikir olduğunu düşündüğünüz tüm hileleri kaldırın
• Kavramsal işleve göre kodu gruplayın (örneğin, yalnızca bir kez çağırsanız bile, belirli bir amaç için kodu uygun şekilde adlandırılmış bir işleve çıkarın)
• Daha basit bir algoritma kullanın (izin verilen koşullar)
• Ortak işlevsellik için iyi bilinen kitaplıkları kullanma

Çok basitleştirilmiş bir cevap: "Kodunuzun yeniden okunma olasılığı ne kadar yüksekse, ne yaptığınızı açıklama yükü o kadar yüksek olur." Bu tarz standartları takip ederek, resmi belgeler oluşturarak, bunu yorum yaparak, daha kolay okunur kod yaparak olabilir ... not olması gerektiği Lütfen, sen de kesinlikle a başkalarının doğru olsa da, daha sonra yeniden okuma yaptığını yüksek ciro ortamı.

Yorumların dokümantasyon olup olmadığını kapsayan başka bir harika konu var.

Yorumlar bazı senaryolarda diğerlerinden daha yararlıdır. Bu o kadar temeldir ki, birçok cevabın ortasında nasıl "anti-comment" olduğunu düşündüğüm hakkında endişeleniyorum.

Kodunuz yıllarca okunmayabilirse, yorumlar sık sık kod yeniden düzenleme, güçlü kod sahipliği ve bol kod incelemelerine sahip olmanızdan daha önemlidir . Başvurunuz karmaşıksa ve bu dilde yetkin bir gözlemci tarafından açıkça görülmeyen teknikler kullanıyorsa, yorumlar sistem yüceltilmiş bir "Merhaba Dünya" dan daha önemlidir . Kod tabanı olabildiğince standartlara uygun değilse, yorumlar altı QA katmanıyla çalıştığınızdan daha önemlidir . Sadece dili öğrenen sekiz kişiden oluşan bir ekip üzerinde çalışıyorsanız, yorumlar ekibinizde sekiz programlama Pulitzer bulunmasından daha önemlidir . Eğer kucağınıza düşen bir yayılma uygulaması varsa,yorumlar, onu sıfırdan temiz bir şekilde oluşturabildiğinizden daha önemlidir .

Bu senaryoların çoğunda, yorumların kullanımını artırmak yerine altta yatan nedeni düzeltmek daha iyi olur mu? Kesinlikle. Ancak bazen kasaba akıllı telefonundan daha fazla parmak izine sahip bir kod tabanına takılıp kalıyorsunuz ve bunu geliştirmenin en iyi yolu, değişikliklerinizi mümkün olduğunca okunabilir hale getirmek ve heck'i yorumlamaktır.

Özel probleminize: yorumlar, kodu karmaşık hale getirecek kadar çok kullanılmamalıdır. Bir altyordamın üst kısmında, bir işlevin neden var olduğunu ve belki de bu yaklaşımı neden kullandığını açıklayan iyi yazılmış bir paragraf, bir sonraki programcının yönlerini almasına yardımcı olmak için genellikle en iyi seçimdir.