Güncelleme
Vurgulama teklifindeki cevabım:
Yorumların Kodlama Standartlarında ele alınmaması gerektiğini belirten ve daha sonra bununla mücadele etmek için bir dizi savunma sorusu listelediğine dair cevabım tek doğru cevap.
Buradaki sorun, bir Kodlama Standartının tam da bir Standart olmasıdır . Son derece sübjektif fikirler gerekir değil bir olmak Kodlama Standardı . En İyi Uygulamalar kılavuzunda olabilir, ancak bu kılavuz Kod İnceleme sırasında bir geliştiriciye karşı kullanılamaz. Bana göre bir Kodlama Standardı, Automated'e mümkün olduğunca yakın olmalıdır. TÜM otomatikleştirilince adlandırma, boşluk bırakma, sekme, parantez, yorum vb. İle ilgili olarak Kod İncelemelerinde çok fazla zaman harcanmaktadır. Hakkında bile cevap tablesve chairsotomatik hale getirilebilir. LINT'ers sözlüklere, Kavram Başına Büyük Harf Çeklerine (Değişken, İşlev, Yöntem, Sınıf vb.) İzin verir.
JavaDoc kontrolü bile bir Çekme İsteği kabul edilmeden önce bir Robot LINT'er tarafından uygulanabilir. Bir çok Açık Kaynak projesi bu kesin şeyi yapıyor. Çekme İsteğinizi gönderirseniz, kod Statik Analiz de dahil olmak üzere bir Travis-CI dosyası ile oluşturulur ve nesnel olarak ifade edilebilecek tüm Kodlama Standartlarını geçmelidir. Hiçbir insan “yanlış yapmak” veya “yorumda bulunmama” ya da değişkenleri isimlendirmenin yanlış yolu hakkında hiçbir şey söylemez. Bu tartışmalar değer vermez ve en iyi şekilde, duygusal kodlamamızın netliğini alabilen üçüncü taraf bir robota bırakılabilir.
Aslında soruyu cevaplamak için , aşağıdaki soruyu nasıl cevaplayacağımıza değinecek bir Standart yazmayı ele almak zorunda kalacağız : Bu yorum size değer sağladı mı? Kodlama Standardı muhtemelen bir yorumun 'değerini' belirleyemez. Bu nedenle, bir insanın bu kontrol listesine girmesi gerekli hale gelir. Bir Kodlama Standardı'ndaki yorumlardan yalnızca bahsetmek, Orijinal Posterin kaçınmak istediği bir kontrol listesi oluşturur.
Bu nedenle yorumlar genellikle derleyici tarafından işlenmez ve çıkarılır. Onların değeri belirlenemiyor. Söz konusu yorum değerli midir? Evet veya Hayır?. Bu soruyu cevaplamak NP zordur. Yalnızca insanlar, doğru şekilde cevap verme şansına sahiptir ve o zaman bile, okuduğu kişi tarafından okunduğu zaman cevaplanabilir; Bu yorumun değeri, hava koşullarından, ev hayatından, katıldığı son toplantıya ve iyi bitmediyse, günün saati, yaptıkları kahve miktarından etkilenir. Resmin daha netleştiğine inanıyorum.
Herhangi bir standartta nasıl doğru bir şekilde ifade edilebilir? Standart, duygusallıktan çok objektiflik hakkında daha fazla olduğu yerlerde, tutarlı ve adil bir şekilde uygulanmadığı sürece yararlı değildir.
Bir Kodlama Standardının mümkün olduğunca Amaç olarak kalması gerektiğine itiraz ediyorum. Değişkenlerin IS hedefi olarak adlandırılma şekli. Doğru yazım, gramer yapısı ve mahfaza için bir sözlükle kolayca kontrol edilebilirler. Bunun ötesinde bir şey, en fazla güce sahip olan kişi tarafından veya "kaş atma" ile kazanılan bir "öfkeli eşleşme" dir. Kişisel olarak, yapmama konusunda mücadele ettiğim bir şey.
Yorum yaptığımda, üçüncü kişide gelecekteki benliğimle konuşurken her zaman yorum yaparım. 5 yıl içinde bu koda dönersem, ne bilmem gerekir? Ne yararlı olurdu, ne kafa karıştırıcı olurdu ve kodda güncel olmayan ne olurdu? Aranabilir bir genel API oluşturmak için kodlama kodu ile üçüncü taraf kendiniz bile olsa, bilinmeyen bir üçüncü tarafa değer sağlayan yorum kodu arasında farklı bir fark vardır.
İşte iyi bir turnusol testi. Projede SADECE biri olsaydı. Projede sadece sen olacağını biliyordun. Kodlama standartlarınızda neler olurdu? Kodunuzun gelecekte temiz, kendi kendini açıklayıcı ve anlaşılır olmasını istersiniz. Her satıra neden yorum yapmadığın konusunda kendin için bir kod incelemesi mi var? Teslim ettiğiniz 100 dosya üzerinde oluşturduğunuz her bir yorumu gözden geçirir misiniz? Değilse neden diğerlerini zorla?
Bu tartışmalarda kaçırıldığına inandığım bir şey de Geleceğin de bu projede geliştirici olduğudur. Değer hakkında soru sorurken, yarının da yorumdan değer elde edebilecek bir kişisiniz. Yani takım büyüklüğü, bence önemli değil. Takım deneyimi önemli değil, çok sık değişiyor.
Bunu gözden geçiren hiçbir yorum kodu yok, bir hız vericinin bir hastayı çökmesini ve öldürmesini engeller. Kodu etkileyen bir yorumdan bahsettikten sonra, yorumdan değil koddan bahsediyorsunuz. Tek gereken birisini öldürmek için eksik bir yorum ise, bu süreçte kokan başka bir şey var.
Bu tür zor kodlama yöntemlerinin çözümü, yazılımın kendisini yazmak için bir metodoloji olarak zaten sağlanmıştır. Ve yorumlarla ilgisi yok. Yorumlarla ilgili sorun, ürünün sonuçta çalışma biçiminde HAYIR etkisi olmadığıdır. Dünyadaki en iyi yorumlar, bir hızlandırıcı içerisine gömülü olduklarında yazılımın çökmesini önleyemez. Veya elektrik sinyallerini taşınabilir bir EKG ile ölçerken.
İki tür yorumumuz var:
Makine tarafından okunabilir yorumlar
Javadoc, JSDoc, Doxygen, vb. Gibi yorum stilleri, bir dizi kodun sağladığı ortak arayüzü yorumlamanın tüm yollarıdır. Bu arayüz sadece tek bir geliştirici (iki kişilik bir ekip için Özel kod), bilinmeyen sayıda geliştirici (örn. JMS) veya bir departman tarafından kullanılabilir. Bu kod, otomatik bir işlemle okunabilir; bu daha sonra bu yorumları, ala HTML, PDF ve benzerlerini okumak için farklı bir yol üretir.
Bu tür bir yorum için standart oluşturmak kolaydır. Herkese açık şekilde çağırılabilir her yöntem, işlev, sınıfın gerekli yorumları içermesini sağlamak için nesnel bir süreç haline gelir. Başlıklar, parametreler, açıklama et. El. Bu, başka bir ekibin kodu bulup kullanmasının kolay olmasını sağlamak içindir.
Delice görünen bir şey yapıyorum, ama gerçekten değil
Bu yorumlar, Niçin bu kodun belli bir şekilde yazıldığını neden görmesine yardımcı olmak için burada. Muhtemelen kodun üzerinde çalıştığı işlemcilerde sayısal bir hata vardır ve bu kod her zaman yuvarlanır, ancak geliştiriciler genellikle yuvarlayan kodlarla ilgilenir. Bu nedenle, koda dokunan bir geliştiricinin, geçerli bağlamın neden bir şey yaptığını anlamasının normal olarak mantıksız göründüğünü anlamasını sağlamak için yorum yapıyoruz , ancak gerçekte bu şekilde bilerek yazılmıştır.
Bu kod türü, bu kadar çok soruna neden olan şeydir. Genellikle yorumlanmaz ve daha sonra yeni bir geliştirici tarafından bulunur ve 'düzeltilir'. Böylece her şeyi kırıyor. O zaman bile, yorumlar sadece NEDEN herhangi bir şeyin kırılmasını önlemediğini açıklamak için var.
Yorumlar güvenilemez
Yorumlar sonuçta işe yaramaz ve güvenilmez. Yorumlar normal olarak programların çalışma şeklini değiştirmez. Ve eğer yaparlarsa, o zaman sürecin daha fazla soruna neden oluyor demektir. Yorumlar sonradan ve asla bir şey olamaz. Kod, bilgisayar tarafından işlenenler kadar önemlidir.
Bu kulağa asin gelebilir, ama benimle kal. Bu iki çizgiden hangisi gerçekten önemli?
// We don't divide by 0 in order to stop crashes.
return 1 / n;
Bu örnekte, önemli olan şey, 'n' nin ne olduğu hakkında hiçbir fikrimizin olmadığı, n'in 0 olması için herhangi bir kontrol bulunmadığıdır. Olsa bile, hiçbir şey bir geliştiricinin n = 0kontrolü kontrol etmeden sonra bırakmasını engellemez. Bu nedenle, yorum yararsızdır ve otomatikleştirilmiş hiçbir şey bunu asla yakalayamaz. Hiçbir standart bunu yakalayamaz. Yorumun, güzel (bazıları için) olmasına rağmen, ürünün sonucuna hiçbir etkisi yoktur.
Test Odaklı Geliştirme
Ürün üzerinde ne sonucu var? Yazılan kodun kelimenin tam anlamıyla birini kurtarabileceği veya öldürebildiği endüstriler titizlikle kontrol edilmelidir. Bu, kod incelemeleri, kod incelemeleri, testler, testler, kod incelemeleri, birim testleri, entegrasyon testleri, denemeler, aşamalar, test ayları, kod incelemeleri ve tek kişilik denemeler, aşamalandırma, kod incelemeleri, testler ve belki de sonunda yapılabilir üretime giriyor. Yorumların bununla hiçbir ilgisi yok.
NO yorumlu, spesifikasyonlu, spesifikasyonları doğrulayan ünite testleri, kodları üretim cihazında çalıştırma sonuçlarının incelemeleri, daha sonra hiç test edilmemiş veya daha önce hiç test edilmemiş herhangi bir şekilde kodlanmış herhangi bir kod içermeyen kod testleri tercih ederim. karşı kod.
Niçin birisinin belirli bir şeyi yaptığını anlamaya çalışırken belgeler güzeldir, ancak yıllar boyunca, belgelerin gerçekten ihtiyaç duyulmadığında 'akıllıca' bir şeyin neden yapıldığını açıklamak için kullanıldığını öğrendim. bu şekilde yazılmak.
Sonuç
Her satırı GEREKTİREN GEREKEN bir şirkette çalışıyorsanız, GARANTİ Projedeki yazılım mühendislerinden en az ikisi, hattın ne yaptığının genel fikrini belirleyen, Perl, Lisp veya Python'da bir otomatik belge programı hazırlamışlardır. , sonra bu satırın üstüne bir yorum ekler. Bunu yapmak mümkün olduğundan, yorumların yararsız olduğu anlamına gelir. Kodu otomatik olarak belgelemek ve bunları 'Her Satırda Yorum Yapma'nın neden zaman kaybettiğine, hiçbir değer sağlamadığına ve potansiyel olarak incindiğine dair kanıt olarak kullanmak için bu komut dosyalarını yazan mühendisleri bulun.
Bir kenara, programlama görevinde yakın bir arkadaşıma yardım ediyordum. Öğretmeni, her satırın belgelenmesi gerektiğine dair bir şart koymuştu. Böylece bu düşünce sürecinin nereden geldiğini görebiliyorum. Sadece kendinize sorun, ne yapmaya çalışıyorsunuz ve bu doğru olanı mı? O zaman kendinize sorun; Bu süreçte sistemi 'oyuna sokmanın' herhangi bir yolu var mı? Varsa, o zaman gerçekten herhangi bir değer katıyor mu? Bir kişi otomatik olarak kodun belirli bir şartnameyi karşıladığını test eden birim testlerini yazamaz ve eğer yapabilselerdi, bu kötü bir şey olmazdı.
Bir cihazın belirli koşullar altında çalışması gerektiğinden, bir insanın içinde olacağından, onları öldürmeyeceğinin garantilenmesinin tek yolu yıllarca süren sınavlar, meslektaşların incelemeleri, denemeler ve daha sonra bir daha asla ASLA kod değiştirmemesidir. Bu yüzden NASA hala bu kadar eski donanım ve yazılımı kullanıyordu. Yaşam ya da ölüm söz konusu olduğunda, sadece 'küçük bir değişiklik yapıp kontrol etmeyin'.
Yorumların hayat kurtarmakla ilgisi yok. Yorumlar insanlar içindir, insanlar yorum yazarken bile hata yaparlar. İnsanlara güvenme. Ergo, yorumlara güvenme. Yorumlar sizin çözümünüz değil.