Müvekkilim mevcut projemdeki yorumların% 25'ini istiyor, nasıl tepki göstermeli? [kapalı]


96

Burada genç geliştirici.

Şu anda şirketimin büyük bir müşterisi için bir web uygulamasında tek başıma çalışıyorum. Geçen ay başladım. Müşteri, her yazılım projesinde yorumların en az% 25'ini ister.

Önceki uygulamaların kodunu kontrol ettim ve işte benim gözlemlerim:

  • her dosya bir yorum bloğuyla başlar (paket, en son güncelleme tarihi, şirketimin adı ve telif hakkı)
  • tüm değişkenler isimleri ile yorumlanır. // nameOfCustomer public String nameOfCustomer

  • Tüm alıcılar ve ayarlayıcılar yorumlandı

  • çok az faydalı yorum

Geliştiriciler, kalite ve kullanışlılık ne olursa olsun,% 25 eşiğine ulaşabilecekleri kadar yorum yapıyor gibi görünüyorlar. Şirketim bana "müşteri istediği gibi yapıyoruz" dedi.

Bu konuda doğrudan müşteriyle konuşmadım. İşte şimdiye kadarki argümanlarım:

  • okumak ve yazmak için gereksiz çizgiler (zaman kaybı)
  • yorumlar bazen güncellenmez (karışıklık kaynağı)
  • geliştiricilerin gerçek faydalı yorumları kullanma ve güvenme olasılıkları daha düşüktür

Bu konudaki öneriniz nedir? Durumu nasıl ele almalıyım?


162
Saçma. Ancak, müşterinin istediği şey buysa ve müşteri size almanız için size iyi para ödüyorsa, o zaman ona verdiğiniz şey budur.
Robert Harvey,

20
Satırların % 25'i (kodla aynı satıra hiç açıklama yapmadığınız anlamına gelir) veya baytların % 25'i ?
RonJohn


10
Burada dikkatli olsan iyi olur. Genellikle bu tür bir beklentinin ardında bir sebep vardır ... Müşterinize bu yorumların faydasız olduğunu söylerseniz,% 25 yorum isteyebilir (ne sebeple olursa olsun) ancak şimdi faydasız olarak adlandırdıklarınız OLMADAN .. Kendini daha büyük belaya bulabilirsin .... Bazen müşteri argümanları seni
şaşırtacak

19
Bu, kurallar çerçevesinde, kariyerinizde gözlemlemek için bol bol fırsatınız olacak bir nesne dersidir: ölçtüğünüz şey aldığınız şeydir . Yorumlarınız için size bir ölçüm verilmiştir ve bu nedenle yorumlarınız alacağınız şeydir. Daha mantıklı bir müşteri size performans, doğruluk, sağlamlık ve maliyetle ilgili ölçümler verir ve ardından bunları elde edersiniz. Ama mantıklı bir müşterin yok.
Eric Lippert

Yanıtlar:


115

Buradaki diğer cevaplar ve yorumlar beni gerçekten bir döngü için attı, çünkü ilk tepkilerime çok karşılarlar ve iş arkadaşlarımda şahit olduğum tutumlara karşı çıkıyorlar. Bu yüzden, sadece muhalif ses olma uğruna, eğer alternatif bir yaklaşım tanımlamak istiyorum .

Bu cevabın yol gösterici ilkesi, "Müşteriyi memnun etmek" dir. Müşteriyi memnun etmek sadece beklentilerini karşılamak anlamına gelmez; onların isteklerini o kadar derinden anlamak, onların ne anlama geldiklerini yorumlayabilmeniz ve istediklerinin üzerinde ve ötesinde yayınlayabilmeniz anlamına gelir. Diğer cevaplara kendimi kötü bulduğum kötü niyetli uyum ilkesine rehberlik ediyor gibi görünüyor; ve ayrıca, tekrarlanan müşterileri elde etmenin kötü bir yolu olduğu için şüpheli ticari uygulama.

Bana göre müşterinin "% 25 yorum istiyorum" dediğini duyduğumda, bu bir iletişimin başlangıcıdır. Benim için buradaki imaların diğer cevaplar gibi "belirli bir sözdizimsel kategorideki rastgeleliği eklemenizi istiyorum" değil, "Çok açıklayıcı bir metin istiyorum, böylece bu kod tabanına yeni başlayanlar hızlı bir şekilde çalışmaya başlayabilir" olduğu açıktır. alıyor gibi görünüyor. Ve bu talebi ciddiye alırdım ve kodun yapısına yeni bir yol gösterici, şaşırtıcı mühendislik kararlarına dikkat çekerek ve bunlara giden mantığı ortaya koyan ve üst düzey İngilizce veren birçok açıklayıcı, faydalı yorum yazmayı düşünüyorum. karmaşık kod bölümlerinin açıklamaları (sürprizleri olmasa bile). Bu niyet ve anlayış başlangıç ​​noktasıdırTartışmanın konusu - konuşmaya başlamadan önce. Bana göre isteğin anlamı o açıklığa kavuşturulmayacak kadar net; Ama eğer belirsiz ise tabii ki onlarla kontrol etmelisin!

Tamam, eğer başlangıç ​​noktası buysa, diyalog nereye gidiyor? İletişim kutusunun bir sonraki kısmı şöyle devam eder:

  1. Bunun, projenin muhtemelen ikinci bir aşamasında, çalışmaya özen gösterdikleri aletin üretiminin üstünde ve ötesinde, ciddi bir ek çaba olmasını beklerdim. Bu süreci ve neden ek iş olduğunu tartışmak birkaç dakikalık bir tartışma olabilir, fakat burada bu konuyu atlayacağım çünkü profesyonel bir programcı olarak iyi yorumlar yapmanın ne kadar zor olduğunu bilmenizi bekliyorum .
  2. “Ciddi bir ek çaba”, daha uzun bir zaman bütçesine ve daha büyük bir parasal bütçeye ihtiyacımız olabileceği anlamına gelir; veya özellik bütçesini azaltmamız gerekebilir; veyayorum kalitesi ve miktarından ödün vermemiz gerekebilir. Bu kısım biraz müzakere olacak. Ancak benim görüşüme göre, bu fazladan işi yapmanın maliyetleri konusunda çok ön plana çıkmalı ve müşteriye bu maliyetleri ödemeye istekli olmalarının çok önemli bir özellik olduğundan emin olmalısınız. Ve eğer - harika! Ekstra zaman ve para alıyorsunuz ve yüksek kaliteli yorumlar alıyorlar. Herkes kazanır. Ve eğer yorumlama özelliğinin onlar için çok önemli olmadığı ortaya çıkmışsa, widget'ları kırma kabiliyetini yitirmeye istekli olmaları veya son teslim tarihinin 20: 6 geç Granuary, 20x6'ya geçmesine izin vermeye istekli olmaları durumunda, herkes kazanır: ve yüksek kaliteli yorumlar oluşturmak için harcadığınız fazla çabayı harcamak zorunda değilsiniz.

Ben iletişim gerektiğini düşünüyorum İşte burada değil gidin:

  1. Müşteriyi düşük kaliteli yorumlarla tehdit etmeyin. Harcamalarını istedikleri çaba düzeyini ve bunun için para ödemek istediklerini seçmenize yardımcı olmalarına izin verin. Onlara% 25 yorum sözü vermeyin ve daha sonra proje oluşturulduktan sonra rastgele otomatikliği yaratarak bu vaadi sunacağınızı söyleyin.
  2. Planlarını gizleme. Onlara% 25 yorum yapmayı vaat etmeyin ve daha sonra ne yapacağınızı söylemeden rastgele olarak otomatikleştirin. Fark ettikleri zaman (eğer olmazsa), ikiniz de büyük zaman kaybedersiniz: Elde ettikleri üründen mutsuz olurlar ve olumsuz sözler duyarsınız.
  3. Onları yorum istemediklerine ikna etmeye çalışmayın. Açıkça yorum yapmak istiyorlar. Çeşitli yaklaşımların mağduriyetini tartışın: evet! Kod temeli geliştirmeyi daha kolay hale getirmenin alternatif yollarını tartışın: evet! Onlara ne istediklerini bilmediklerini söyleyin: ha, hayır. Onlara istediklerini elde etmek için onlarla çalışmak istersiniz; bu yüzden bunun ne olduğunu anlayın ve sahip oldukları kaynaklar yetersiz olduğunda, en çok önem verdikleri özelliklere öncelik vererek, onayladıkları bir bütçeyle onlara en iyi şekilde nasıl sunacaklarını anlayın.
  4. Yorum yazmanın ne kadar zor olduğu konusunda mazeret etmeyin. Kod yazmak zor; hata ayıklama kodu zordur; yorum yazmak zor. Kolay olsaydı, sizi işe almazlardı. Şikayetleri atlayın ve ilgilendikleri noktaya, yani gereken ekstra çabanın kendilerini nasıl etkilediğine doğrudan bakın.

3
Soruyu güzel olumlu almak :-)
cmaster

9
@ThorstenS. Çalıştığım şirket savunma sanayinde yaptığı işin üstünlüğünü yapıyor. Psişik güçlerini kontrol ettirmek isteyebilirsin. Ayrıca, asla "dileklerini nasıl yazdıklarını yorumlamadım" demedim: "% 25 yorumu" ciddi ama tesadüfi bir istek olarak ele alırdım - asıl istek "büyük bir teknik yazı gövdesidir" ve% 25 Bu vücuda girmeyi umdukları çaba düzeyi hakkında bir gösterge, muhtemelen esasen keyfi olarak seçtiler, ancak yine de kaçırmamanız gereken bir hedef.
Daniel Wagner

12
Bir programcı tutsaydım, Bay Daniel Wagner, işe almak istediğim türden bir adamdı.
Joe Gayetty

5
Bu, isteğin mektubunun aksine, isteğin amacını belirlemek ve ele almak istediği için büyük bir cevaptır. IMO Bu, bir geliştirici ile yalnızca kod yazan bir kişi arasındaki farktır.
Justin Ohms

6
Bu yorumların bakım maliyetini artıracağını açıkça belirtmeniz iyi olur . Oluşturulduktan sonra sürekli güncellenmeleri gerekir , ya da zaman ve para kaybıdır. (Yarın + 1’e kadar beklemek, böylece gerçekten rep. Almak için;) Hak ediyorsun.)
jpmc26

83

Müşteri kraldır. Müteahhit olarak, müşterinin kalite standardı olarak tanımladığı şeyi yerine getirmelisiniz. Yoksa dışarı çıkma riskin var.

Bu söyleniyor, (burada zayıf) kalite standartlarının nasıl tanımlandığı önemli.

  • Sözleşme kalite standartları: Teslim edilen kodlara uymalı, aksi takdirde sözleşmenin ihlalidir. Seçenek yok.

  • Resmi kurumsal kalite standartları: Mükemmel şekilde çalışsa bile, uymayan kod, pek çok kişi tarafından kötü kalite olarak kabul edilir, bu sayede hepsini daha iyi bir uygulamaya dönüştürmeden önce yaşlanacaksınız. Daha da kötüsü: Bu tür kalite ölçütlerini otomatikleştirmek ve meşrulaştırmak için iyi bilinen araçlar kullanılabilir (örneğin, sonar küpü ). Neredeyse başka seçenek yok.

  • Müşteride bir kaç kişi tarafından belirlenen geçici kriterler. Burada tartışma yapabilirsin. Umut var :-)

Bu son durumda, bir miktar esneklik olabilir ve bunu diplomatik olarak yapmaya çalışabilirsiniz. İşte müşterinin kriterlerine aykırı bazı argümanlar:

  • Verimlilik sorunu: Kodlama iki kez yapılır (bir kez İngilizce, bir kez kod).
  • Doğruluk sorunu: Kodda değişiklikler yapılırsa, yorumlarda yapılmaları gerekir, aksi halde yorumlar işe yaramaz hale gelebilir.
  • Yeniden düzenleme sorunu: Yeniden düzenleme aracı, yorumlardaki değişken adlarını işlemiyor.
  • Risk konusu: Yorumların belirsizliği (veya eskimesi), kafa karışıklığı ve böcekleri artırma riski doğurabilir.
  • Miktar kalite değil
  • StackOverflow ile ilgili bu işe yaramaz yorumların komik koleksiyonu .
  • Yüksek bir oranın bile bir kod kokusunun işareti olabileceğini savunan bu makale .

Ancak, kötüye karşı konuşmak ve müşteriyle yüzleşmek yerine, daha iyi yaklaşımları teşvik edebilir misiniz:

  • Kodu temizleyin (kitabı müşterinize önerin: yorumlara ve kendi kendine belge koduna adanmış inandırıcı bir bölüm var).
  • Belgelendirme pratiği: Tutulması en zor olan şeyler ve bu nedenle, örneğin sınıflar arasındaki ilişki ve etkileşim gibi en değerli bilgiler ayrı bir belgede daha iyi belgelenir (örneğin, 1000 yorum kelimesi yerine UML resminde?)

Müşteri hala ikna olmuyorsa, javadocveya gibi yorumlarla otomatik olarak dokümantasyon üreten araçları kullanarak deneysel bir alternatif önerebilirsiniz doxygen. Odağı miktardan (kodun% 25'i) kaliteye (anlaşılabilir bir javadoc üretmek) kaydırmayı önerin.


7
Müşteri kral ise, bu tür müşteri krallıklarının ne kadar verimsiz olduğunu göstermeye gider!
Steve

82
Müşteri kraldır. Müteahhit olarak, müşterinin kalite standardı olarak tanımladığı şeyleri göreceksiniz. Ya da dışarı çıkma riskiniz var ”. Müşterilerine istediklerini düşündüklerini ve gerçekte ihtiyaç duyduklarını vermeyenler çok uzun süre hayatta kalamazlar. Aslında, bu gerçek istismar durumlarını yalnızca gerçek sorunlu müşteriler için ayırdım - ve ikinci bir doza hiç gerek olmadı.
David Schwartz

6
@DavidSchwartz evet, kesinlikle. Bazen müşteriler bir şeylere ihtiyaçları olduğunu düşünüyor ancak gerçekten bir başkasına ihtiyaç duyuyorlar. Danışmana veya geliştiriciye ikna etmek için ve cevabımın 2 / 3'ü tam olarak bu konuda. Ancak bunların hepsi sözleşmeye bağlı içeriğe ve sağlayıcı ile müşteri arasındaki güven düzeyine bağlıdır. Bu yüzden, müşteri kuralının kral olduğunu hatırlatmak gerekir (aslında müşterilerle birkaç kez deneyimledim, optimal çözümle ilgili uzun bir tartışmadan sonra, bu cümleyi yazdım ve bu durum ani bir tutum değişikliğini ve tartışmaların dikkatli bir şekilde yeniden gözden geçirilmesini tetikledi ;-) ).
Christophe

7
"Doğruluk sorunu: Kodda değişiklikler yapılırsa, yorumlarda yapılması gerekir, aksi takdirde yorumlar işe yaramaz hale gelebilir." Sadece işe yaramaz olmaktan bile daha kötü olduğunu söyleyebilirim . Güncel olmayan bir yorum, gerçeğin kaynağı olmasını ve ona güvenmesini beklediğinizde, bir hataya (veya bunun bir hata olduğunu düşündüğü için geri dönen biri) çok hızlı dönebilir.
Hamatti

11
@Hamatti Gerçekten. Bir keresinde orijinal niyeti okuyan bir satırın arkasındaki deşifre etmek için hatırı sayılır bir zaman harcadım,i++; // count down
TKK

18

Müşteri, her yazılım projesinde yorumların en az% 25'ini ister.

Müşteri gerçekten yorumların% 25'ini istiyor mu veya müşteriniz kodunuzun mümkün olduğunca açıklayıcı olmasını istiyor mu?

IMHO, müşteri ne istediğini bilir, fakat ne istediğini bilmez. Bir müşteri bir geliştirici olmadığından ve kendi çalışanlarından / müşterilerinden geri bildirim aldığından, müşteriniz buzdağının yalnızca üst kısmını görür.

Müvekkilinizin bazı sahte bilgilere sahip olduğunu ve kodun iyi belgelenmiş ve kolay ve ucuz bir şekilde muhafaza edilmesini istediğini ve bunun için araçların yorum olduğunu düşünüyorum (aklında).

Onunla konuşmayı deneyin ve kendisini açıklayan iyi kod yazmış bazı kod parçacıklarını ve diğer açıklamaları içeren kötü yazılanları hazırlayın. Sadece bir kaç satır. Gerekirse bunu gösterin ve kelimelerinize resim olarak kullanın.

Müşteriniz / amiriniz / ne olursa olsun konuşun ve onlara sürüm kontrolünün modern ilkelerini (dosyanın başında yorum yapılmasına gerek yok) ve temiz kodu ( kitabı da öneririm ) ve böylece kendi kendini açıklayan kodu anlatmaya çalışın .

Belki de, yeterince iyi gösterebilir ve müşterinize sadece kodları değil, temiz kod istediğini anlamasını sağlarsanız, siz ve ekibiniz daha iyi kod yazabilir (çok daha az yorum ile) ve derhal saklanmaya değer bir geliştirici olduğunuzu gösterebilir. .


13
Kendini açıklayan kod, hoş bir ilkedir. Ne yazık ki, gerçek dünyada o kadar iyi çalışmıyor. Arayüzler ve karmaşık iç süreçlerin belgelenmesi gerekir ve basitçe güzel isimleri seçmek yeterli değildir. Bu değerler hangi birimlerdir? Ölçeklendirme faktörleri? Örnekleme oranları? Bu yöntemi çağırmak ne zaman güvenlidir ve ne zaman olmaz? Hangi koşullar için hangi istisnalar atılır? Ve benzeri vb. Kodunuzu sürdürülebilir kılan şey budur. Gerçek dünya, bir kod pasajının asla temsil edemeyeceği bir karmaşıklığa sahiptir ve bu nedenle bunun doğru bir şekilde belgelenmesine ihtiyacınız var.
Graham

2
@Graham Evet, yorumlar tamamen kaçınılmaz değildir. Ancak yorumlar kod gibidir: Ne kadar çok yaparsanız, o kadar çok bakım yapılması gerekir. Özlü kalmak inanıyorum yardımcı olur.
Robert Dundon

Bir şeylerin tamamen işe yaramaz olduğunu söylemek istemiyorum, ancak tam olarak işlev veya değişken adı gibi yorumlar faydalı değil. Kısa kod, yorum yapılmadan mümkün olduğunu ve yorum içermeyen bir ortamı zorlamaması gerektiğini göstermelidir. Hangi istisnaların atıldığını göstermek veya işlevsellik hakkında daha fazla bilgi vermek istiyorsanız, fonksiyonlar için özet etiketini kullanabilirsiniz. Bağımlılıkları işaret etmek istiyorsanız, ihtiyaç duyulan nesneyi giriş parametresi vb. Olarak modelleyin. Her şeyi yapmanın mükemmel bir yolu yoktur, her iki dünyanın da en iyisini elde edin
Chrᴉz

@ Chriz Kesinlikle, katılıyorum. Yorumlar bilgi eklemezse, onları dışarıda bırakın. Ama başka bir cevapta dediğim gibi, yüzde gerçekten bir kod kokusu testidir. Haklısın, denetçi kontrol eder, herkes devam eder. Endişe, kodlarını gerçekten açıklayan ve kendileri hakkında açıklayan ve bu tür şeyler hakkında hiç düşünmeyen biri.
Graham

12

Bu bana aptal Stack Overflow cevaplarını hatırlatıyor, bir satırdan sonra, kelimenin tam anlamıyla "minimum karakter sınırına ulaşmak için burada bir metin" yazdığını görüyorsunuz.

Bu olduğunda, iki insan grubunun hatalı olduğu iddiaları yapılabilir:

  1. Sınırı koyan insanlar - açıkça aşırı ve insanların yapay ses eklemeden düzgün şekillendirilmiş bilgilerini göndermelerini önler

  2. Bu bilgiyi gönderilen insanlar değildi sistem yerine daha gerçek maddeyi eklemek için onları istendiğinde düzgün oluşmuş, daha sonra yapay gürültü eklendi

Bazen bir soru basit hem olacak ve konuyla ve birkaç kelime daha söylemek daha çok şey yoktur. Ancak, bu son derece nadirdir. Neredeyse tüm durumlarda, söylenecek çok fazla madde var. Başka bir şey değilse, bir karakter kısıtlamasının üstesinden gelmenin yolunun sadece rastgele gürültüyü yayınlamaktan ibaret olmadığı açıkça görülmelidir .

Karşılaştığınız bu yorum durumu neredeyse aynı. Geliştiricileriniz yorumlar için bir istekte bulundular ve bunu rasgele sesleri kodlarına dökerek uyguladılar. Değişkenlerin adlarının belgelenmesi, değişkenlerin bildirimlerinin hemen yanında, vandalizmdir . Bu asla olmamalıydı.

“Ama başka% 25'e nasıl ulaşabiliriz?” Maddenin gerçek yorum yazarak. İşlevlerin etkisini belgelemek için daha fazla kelime, daha iyi kelimeler, en iyi kelimeler kullanın. Açıklamalarınızı genişletin. Kenar kasalarını daha ayrıntılı olarak tanımlayın.

Bununla birlikte, orijinal noktaya geri dönersek, müşteri burada da kısmen hatalıdır, çünkü "kaynak kodun% 25'i" son derece keyfidir. Sonuçta, yine de, onlar müşteri, bu yüzden en iyi şekilde yararlanın. Ama ben "en iyisi" demek istiyorum. Şimdiye kadar olduğu gibi "en kötü" değil.


5

Bu gereksinimle ilgili büyük karışıklığın ne olduğunu bilmiyorum.

Sadece kodunuzun temel oksijenlendirilmesi ile muhtemelen zaten% 10'desiniz. Ve kendiniz için yazdığınız yorumların% 5'ini alalım (bazıları daha fazla yazıyor, ancak% 5'i sessizlik yemin etmediyseniz muhafazakar bir tahmin gibi görünüyor). Bu noktada% 15 civarındadır (evet, biliyorum,% 90'ın% 5'i% 5'ten az, nitpick yok). Oksijeniniz% 10'dan azsa, belki de yöntemleriniz çok uzundur; onları daha küçük (çoğunlukla özel / korumalı) olanlara bölmek veya daha genel yardımcı sınıfları vb. kullanmak iyi bir fikirdir.

Şimdi, yorum metninin geri kalanı için - tasarım düşüncelerini ve kullanım senaryolarını sınıf / dosya düzeyinde yorumlara ekleyin. Bazı tablolara veya ASCII-art'a (veya işlendiğinde daha güzel görünen şeyler üreten doxygen koduna) sahip olun. Elbette, projenizin ne hakkında olduğunu bilmiyorum, ama bunu aptalca yorumlar yapmadan (oksijenasyon kazanı hariç) yapıp% 25'e yakın bir şey elde edebileceğinizi düşünüyorum.

Sadece% 20 ve% 25 olmasa bile - Müşterinin bu numarayı keyfi bir şekilde verdiğinden ve bunun için iyi olacağından eminim. Neyse, yorumların neleri içermesi gerektiğini tartışmak için onlarla konuşun; ve memnun olup olmadıklarını görmek için onlara yorumlanmış bir örnek dosya gösterin. Eğer öyleyse o kadar, eğer bir şeyin eksik olduğunu düşünürlerse size neyin eksik olduğunu söylerler. Size "Ekstra bir yorum yapamayız ancak yine de bazılarını eklemenizi istiyoruz" diyemeyecekler.

PS - Nasıl ulaşabileceğinizi görmek için standart Java konteynerlerinin koduna bakın, oh,% 70 ya da öylesine ...


5

Kodunuzda% 25 yorum sahibi olmak, mükemmel bir hedeftir ve müşteriyi mutlu eder. Şimdi "i + = 1; // i 1 'i artır" gibi% 25 crappy dolgu yorumları yazmak sizin için olmalı, bu yüzden zaman ayırın, faydalı yorumlar yazın ve aslında yapmanız gereken bir şeyi yapmak için para aldığınızı hissedin neyse.


Bu da güzel bir tane +1. Yorum oranıyla ifade edilen iyi bir hedef olup olmadığını bilmiyorum, ama belki çoğumuz bu '' hedefinize yararlı bir şekilde, bilmeden ulaşırız ... Son zamanlarda eski bir kod parçasını buldum 80'lerde kariyerimin başlangıcında, yenilikçi yüksek performans algoritmasıyla yazdım: yorumların sadece% 10'unu oluşturuyor, ancak geriye dönük olarak keşke daha çok yer alsaydı ;-)
Christophe

4

Hepimiz bunun saçma bir gereklilik olduğunu biliyoruz. Buradaki ilginç soru

nasıl tepki verilir?

Sorunları görünür kılmaya büyük inanan biriyim. Burada paranın konuşması gerçeğini kullanırdım.

Bunu yapmamı isteyin, bundan eminim, teklifime% 1 ekleyeceğim. Oh, ancak gelecekteki bakım tekliflerine% 20 ekleyecektir.

Sadece bir kez neden onlara iyi isimlerin amacının yorum yapma gereğini önlemek olduğunu öğrettiğimi sordular.

Alternatif olarak, projenin arkasındaki fikirleri hızlandırmak için belirlenmiş bir dizi nitelikleri olan bir bakım programcısı almaya yönelik belgeler oluşturmayı teklif ediyorum. Ya da kesin, size% 25 yorum verebilirim. Sana bağlı.


3

Evet, aptal kurallarla olan hayal kırıklığınızı anlıyorum. Gibi yararsız yorumlar ile birçok program okudum

x = x + 1; // add 1 to x

Ve kendime diyorum ki, artı işareti ne demek? Vay, söylediğin için teşekkürler, bunu bilmiyordum.

Ancak bu, müşterinin faturayı ödediğini söyledi. Bu nedenle, onlara istediklerini verirsiniz. Bir araba mağazasında çalışıyor olsaydım ve bir müşteri bir kamyonet istediğini söyleseydi, onunla gerçekten bir kamyonete ihtiyaç duyup duymadığını ve onu taşımasını beklediği şeyi sorguladığını söylemezdim. Ona bir kamyonet satardım.

Tamam, müşterilerin istediğini söylediği ve gerçekte ihtiyaç duyduğu şeylerin o kadar uzakta olduğu zamanlar var, konuyu onunla tartışmaya çalışıyorum, belki de onu daha rasyonel bir şey üzerinde anlaşmaya ikna etmeye çalışıyorum. Bazen bu işe yarar, bazen işe yaramaz. Sonunda fikrini değiştiremezsem, istediğini veririm. Daha sonra geri dönüp diyorsa, Oh, iş gereksinimlerimi gerçekten karşılamadıysa, ilk kez yapmasını istediğimiz şeyi yapmak için onu daha fazla ücretlendirebiliriz. Müşteri ile ne kadar pazarlık edeceğiniz, uzmanlığınıza ne kadar güvendikleri, sizinle olan sözleşmelerinin organizasyona nasıl uyduğu ve açıkçası ne kadar saçma sapan olduklarına bağlıdır.

Bana göre, bir sözleşmeyi kaybedeceğimi düşündüğüm için zor bir durum olduğunu düşündüğüm için çok nadir bir durum olurdu.

Şirketinizin pazarlık yaptığı kişilerin bu% 25'lik kuralı icat edenlerin olabileceğini veya olmayabileceğini unutmayın. Yukarıdan onlara uygulanan bir kural olabilir.

Beş olası cevap görüyorum:

Bir. Patronunuzu ya da müşteriyle görüşenleri bu konuda tartışmaya ikna edin. Muhtemelen bu hiçbir şeyi başaramaz, ama deneyebilirsiniz.

İki. Yapmayı reddet. Bu muhtemelen kovulmanıza neden olur veya şirket sizinle anlaşırsa sözleşmeyi kaybetmenize neden olur. Bu verimsiz görünüyor.

Üç. Boşluk doldurmak için gereksiz yorumlar yazın, kodda olanları tekrar eden ve bu kodu değiştirebilecek herhangi bir programcının 2 saniye içinde görebileceği yorum türlerini yazın. Bunun gibi çok fazla yorum gördüm. Yıllar önce, aşağıdaki gibi parametreleri listeleyen her fonksiyonun önüne yorum blokları koymamız gereken bir şirkette çalıştım:

/*
GetFoo function
Parameters:
  name: String, contains name
  num: int, the number
  add_date: date, the date added
Returns:
  foo code: int
*/
int GetFoo(String name, int num, Date add_date)

Bu tür yorumların bir bakım yükü olduğuna dair itiraz, onları güncel tutmanız gerektiği için geçerli değildir. Onları güncel tutmaya gerek yok çünkü hiçbir ciddi programcı onlara bakmayacak. Bununla ilgili herhangi bir sorunuz varsa, ekibin tüm üyelerine işe yaramaz, gereksiz yorumların göz ardı edilmemesi gerektiğinden emin olun. Bir fonksiyonun parametrelerinin ne olduğunu veya bir kod satırının ne yaptığını bilmek istiyorsanız, kodu okuyun, işe yaramaz yorumlara bakmayın.

Dört. Gereksiz değersiz yorumlar ekleyecekseniz, belki de onları oluşturmak için bir program yazmanın zamanı gelebilir. Önünde bir yatırım var, ama yoldan yazarak bir demet kurtarabilir.

Bu işe ilk başladığımda, çalıştığım bir şirket "Belgeleri sizin için yazıyor! Her program için eksiksiz bir dokümantasyon!" Olarak tanıtılan bir program kullandı. Sistem, tüm değişkenlere esasen anlamsız isimler vermemizi ve her değişken için anlamlı bir isim veren bir tabloya sahip olmamızı gerektirdi, bu yüzden temelde "otomatik dokümantasyon", bizi anlamlı bir adla kullanmaya zorlayan anlamsız ismin yerini aldı. Mesela - bu COBOL ile çalıştı - programınızda şunu söyledi:

MOVE IA010 TO WS124

ve dediler ki bir "dökümantasyon" satırı oluşturdular

COPY CUSTOMER NAME IN INPUT RECORD TO CUSTOMER-NAME IN WORKING STORAGE

Her neyse, kişi kesinlikle kolayca eşit miktarda değersiz belgeler üretmek için bir program yazabilir. Gibi bir satır oku

a=b+c

ve yorumu oluşturun

// add b to c and save result in a

Vb.

Beş. Aptal kuraldan en iyisini yap. Yararlı ve anlamlı yorumlar yazmaya çalışın. Hey, iyi bir egzersiz olabilir.

Oh, bu arada, metriği her zaman oynayabileceğinizi ekleyebilir miyim?

Bir işveren, programcıların verimliliğini, haftada kaç satır kod ürettiğimizi ölçmeye başlayacaklarını söylediklerini hatırlıyorum. Bunu bir toplantıda söyleyince dedim ki, Harika! Puanımı kolayca artırabilirim. Daha fazla yazı yok

x=x+4;

Bunun yerine yazacağım:

x=x+1;
x=x+1;
x=x+1;
x=x+1;

Döngüler? Unut gitsin, kodu on kez kopyalayıp yapıştıracağım. Vb.

Yani burada, eğer yorum satırlarını sayacaklarsa, her bir satırı kısaltın ve bir sonraki satırda fikre devam edin. Yorumlarda neler olduğu konusunda bir değişiklik varsa, mevcut yorumu güncellemeyin. Üzerine bir tarih koyun, ardından tüm metni kopyalayın ve "Güncellenme Zamanı" ile yeni bir tarih yazın. Müşteri bunu sorgularsa, onlara tarihi korumanın gerekli olduğunu düşündüğünüzü söyleyin. Vs vs.


2

Keyfi ölçümler, birçok projede yaşamın gerçeği gibi görünüyor ...

Bu genellikle daha karmaşık kodlara yol açan azami Döngüsel karmaşıklık gibi aptal şartlarda görülür, çünkü uyumluluk sağlamak için fonksiyonlar gereksiz yere bölünür veya bazı keyfi SLoC uzunluklarını aştıkları için dosyaların ayrılması gerekir

Yorumlar kodu eklemeli ve neler olduğunu açıklamalıdır (ve yalnızca kodu tekrar etmeyin!).

Bununla birlikte, müşterinizin istediği şey buysa ve şirketiniz, QA Yöneticiniz bir sağduyulu doz geliştirmezse, takılıp kalmışsınız demektir.


Evet. Keyfi kurallar, insanların kuraldan yararlanmak için davranışlarını değiştirmelerine neden olur. Bürokrasinin sorunu budur. İnsanların bir kuralı nasıl oluşturabileceklerini ve kuraldan etkilenen kişilerin ne yapacaklarına karar verirken bunu dikkate alabileceğini düşünmemeleri beni şaşırtıyor. Sonra boşlukları tıkamak için daha fazla kural ve boşlukları tarafından oluşturulan boşlukları tıkamak için daha fazla kural vb.
Jay

2

Kısa vadede gerçekten yapabileceğiniz hiçbir şey yoktur. Onunla birlikte git.

Ayrıca, pasif agresif protestolar ve kodun aptalca şakaları hakkında bu başlıkta gördüğüm tüm aptalca fikirleri görmezden gelmelisin.

Müşteri ile bir güven ilişkisi geliştirdikten sonra, akıl yürütmenizi dinlemek için daha iyi yerleştirilirler - bunun bir zamanlar etkili olan bir kişiden saçma bir talep olduğunu ve kurum içinde çok az desteğe sahip olduğunu görebilirsiniz.

Hiçbir koşul altında, müşterinin izni olmadan buna karşı çıkmamalısınız.


2

Buradaki programcı arkadaşlarımın gösterdiği hayal gücü eksikliği beni hayal kırıklığına uğrattı.

Bana öyle geliyor ki, müşteri biraz araştırma yaptı. Kalite kodunun tipik olarak yorumların yaklaşık% 25'ini içerdiğini bir yerde okumuş olabilir. Belli ki yolun aşağısındaki bakım konusunda endişe duyuyor / endişeleniyor. Şimdi, bu sözleşmeyi bir sözleşmeye bağlanması gereken bir gereksinimler belgesinde nasıl somutlaştırır? Bu kolay değil. İmkansız bile olabilir. Yine de, bazı kalite göstergelerini sıralamak için parasının karşılığını alacağından emin olmak istiyor.

Bu bana aptalca ya da saçma gelmiyor. Gereklilikleri yazan insanlar büyük olasılıkla programcı değil. Daha önceki bir projede kötü bir deneyim yaşamış olabilirler. Bakım görevlileri şikayet ediyor: "Bu işlerin hiçbiri belgelenmedi!". Bir sonraki proje için yeni gereksinimler yazarken kulaklarda çalıyor.

Kodunuzu belgelemek ve bakım çetesi için içerik sağlamak konusunda ciddi iseniz, bu gereksinim otomatik olarak yerine getirilecektir. Yani bu konuda bir kedi olmayın!

Sonunda,% 21 veya% 29 olsun, kimse umursamaz. Müşteri bazı bağımsız geliştiriciler tarafından eşyalarını gözden geçirir ve ne yaptığını daha iyi anlardı.


1
Soru kesin olarak yorum oranını hedef olarak ifade etmenin geri tepeceğini gösteriyor. Müşterinin, bir başka geliştirici tarafından (ekipte? Dışarıdan? Hangi temel bilgi ve becerilere sahip?)) Başka bir geliştirici tarafından anlaşılması gereken bir hedef hedefi olması ve% 25 (esnek) bir kılavuz olarak vermesi daha etkili olurdu. Bu şekilde ifade etmek, müteahhitler tarafından daha iyi anlaşılır ve temiz kod gibi daha iyi alternatifleri teşvik ederdi.
Christophe

0

Şu anda bu projede çalışmayan insanların var olduğunu anlamayan birçok programcı ile tanıştım.

Onlar için bildikleri her şey, herkes tarafından bilinir.

Birisi şu anda biliyor her şeyi bilmiyorsa, o zaman bu insanlar kendilerine "aptal".

Bu standart ile insanları yorum yazma alışkanlığına girmeye zorlayabilirsiniz.

Zamanın% 99'una faydasız yorumlar yazabilirler, ancak bazen "HER ŞEYİ BİLİYOR" ifadelerinden birini yazabilirler ve takımda yeni bir kişi aslında 16 saatini bir hatayı bulmak için harcayamazdı (birisinin çözdüğü, ama sonra başka bir nedenden dolayı geri alınmadı) bu, kodun bu noktasında bir yorum ile açık olurdu.

Belirsiz hataların olduğu satırlarda yorum yapmak, gelecekteki programcıların bir programı tamamen kazara kırmalarını önlemeye de yardımcı olabilir (özellikle "kırılıyor" - bir bölüm hızlıca test yaparken açık değildir).


3
10000 maymunun daktilolara çarpmasına izin vermemizdeki sorun, değerli bir şey yazmadıkları değil, ama kaybolan nadir taşların çöp yığınında bulunması zor.
Deduplicator
Sitemizi kullandığınızda şunları okuyup anladığınızı kabul etmiş olursunuz: Çerez Politikası ve Gizlilik Politikası.
Licensed under cc by-sa 3.0 with attribution required.