Önce Kod Belgeleri? [kapalı]

11

Kod yazmadan önce, önce kod kodunu oluşturmaya çalışan var mı? Bunu daha önce düşünüyordum çünkü somut bir arayüz yazmanın yardımcı olacağını düşündüm ve sınıfların nasıl etkileşime girdiğini düşünerek ilk tasarımınızın zemine oturmayacağından emin olabilirdim. Bu iyi bir fikir mi? Kimse denedi mi? arşın

documentation

— arşın
kaynak

2

Evet. İyi fikir. İnsanlar her zaman yapar. Daha ne bilmek istiyorsun?

— S.Lott

9

Bu öznel bir soru. Birisi en azından bir süredir yaptı, bu yüzden cevap evet olmalı. Şahsen ben sadece atlamayı ve önce bir prototip yapmayı tercih ediyorum, çünkü kaçınılmaz olarak daha iyi bir tasarımı bu süreçte yaklaşık 5 kez yeniden keşfedeceğim. Karmaşık bir şeyle uğraşırken, önce bir parça kağıda bir şey çiziyorum. Önemsizse, o zaman hemen içeri giriyorum. StyleCop daha sonra boşlukları doldurmama yardımcı oluyor.

— Meslek

2

Harika bir fikir, aksi takdirde belgelenmemiş özellikler elde edersiniz.

— chrisw

8

@ S.Lott Soruyu sorduğu basit gerçeği, farkında olduğunuzdan emin olduğum için biraz daha bilgi aradığını ima ediyor. Ama öyle görünüyor ki diğer insanların hataları hakkında gizli yorumlar yapmayı tercih ediyorsun.

— Kenneth

2

Kabul testleri yazdıysanız ve daha sonra bu Kabul testlerini yerine getirmek için TDD kullandıysanız daha iyi olurdu;).

— Martin Blore

5

Evet.

Kodunuzun tam olarak ne yapacağını düşünmenizi sağlar . Fikir, kodun herhangi bir kısmı ile başlayabilir ve o modülü tamamlamak için ne yapılması gerektiğini tam olarak biliyor olabilirsiniz.

Ayrıca çizim tahtasında bir şeyi düzeltmek IDE'den daha kolaydır.

— Maxpm
kaynak

12

Düzeltmesi daha kolay, evet. Nadiren fark edilmesi daha kolay. Tasarımlar, bunları uygulamaya çalışana kadar neredeyse her zaman iyi görünür.

— CaffGeek

@Chad Bu doğru. Cevabımı bunu yansıtacak şekilde düzenledim.

— Maxpm

4

Katılmıyorum. Öncelikle eksiksiz dokümantasyon oluşturmak, bir sonraki adımın nereye gideceğini bilmek için yeterli dokümantasyondan çok daha kötüdür. Değişim olur. Doğru yöne gidip gitmediğinizi bilmenin bir yolu yoktur ve bunu anladığınız zaman, geride kalırsınız. Neyin işe yaradığını öğrenin, ilerledikçe geliştirin ve düzeltin, kodun en güncel belgeler olmasına izin verin.

— Zachary Scott

4

Elbette, bir hatayı düzeltmek veya yeni bir gereksinimi karşılamak için kodunuzu değiştirir değiştirmez belgeleriniz güncel değildir. Yürütülebilir testler olarak belgeleme yolu budur!

— 41'de Johnsyweb

Fikirleri önceden çizin (taslak / taslak) evet, ancak dokümantasyon oluşturmayın. Çok fazla çaba harcamayı tercih etmedikçe, tasarım pratik uygulamaya konduğu için başlangıçtaki çabaların çoğunu atacaksınız. Ayrıca, sadece genel veya dahili sınıflar / yöntemler tam olarak belgelenmelidir (tam açıklama ve parametreler dahil). Özel yerel malzemelerin ileride başvurmak için ne yaptıklarını açıklayan tek gömlekleri olmalıdır, ancak daha fazlası her şey bir israftır, çünkü bunlar yine de dokümantasyon oluşturma aşamasında kaçınılmaz olarak atlanacaktır.

— Evan Plaice

10

Bunu düşünmenin iki yolu vardır:

1) Word belgelerinde, Wiki vb. Belgeler. Tanım olarak, tam olarak belgelendirilecek bir kodunuz olmadığı için tam bir kod belgelerine sahip olamazsınız. Önce yükseklik seviyesi tasarımı, varsayımlar, arayüzler ve sözleşmeleri belgelemeyi deneyebilirsiniz.

2) Yürütülebilir testler olarak dokümantasyon. Yürütülebilir birim testlerinin en iyi dokümantasyon olduğunu belirten bir düşünce okulu vardır. Bu düşünce okulu, kodu (TDD) yazmadan önce bu tür belgeleri de savunmaktadır. Aynı zamanda, tüm sistem için tüm testleri doğru bir şekilde yazmazsınız. Önce kullanım senaryolarına göre ayırırsınız, ardından kullanım senaryosuna göre testler ve kodlar yaparsınız.

— Yuriy Zubarev
kaynak

2

TDD için +1. Kesinlikle dokümantasyondan daha iyi bir seçenek, daha sonra kod değişirse önemli miktarda dokümantasyonu değiştirmek zorundasınız.

— Ethel Evans

Ayrıca TDD biçimindeki belgeler için +1.

— sevenseacat

ürün var olmadan önce tüm ürün belgelerine sahip olabilirsiniz. Bunu yaptım, bir gereklilik olan projelerde çalıştım. Ekran görüntüleriniz olmayacak, ancak diğer her şeye sahip olabilirsiniz (ekrandaki öğelerin konumunu temsil eden Visio diyagramları dahil).

— 45'te jwenting

@jwenting Ben de var ve 200'den fazla sayfa kelime belgelerinin yanı sıra diyagramların bir koleksiyon oldu. Sadece tam bir zaman kaybı olmakla kalmadı, aynı zamanda tasarımın nihai ürüne dönüştükçe sürekli olarak güncellenmesi için 2 ayın ve PM'lerin önemli bir zamanının olması gerekiyordu. Aslında Balsalmiq kullanan grafik maketlerle çok daha hızlı giderdi. Bir dahaki sefere bunun bir gereklilik olduğu bir proje üzerinde çalıştığımda, başka bir kişinin tam zamanlı olarak yönetmesi için atanması gerektiğine dikkat çekeceğim çünkü bu, sürdürmek için ne kadar çaba gerektiriyor.

— Evan Plaice

Bireysel bileşenlerin ve şemaların genel tasarım varsayımları için temel kanıtları için +1 TDD (varsayım üzerine vurgu, çünkü gerçek tasarım, şemanın 1-1 uygulaması olarak değil, en iyi pratik uygulama olarak yazılmalıdır, bunlara bir nedenle varsayımlar denir ). Tüm genel / dahili sınıfların / yöntemlerin / özelliklerin tam yazılım dokümantasyonu bir dokümantasyon oluşturucusundan geçer (önce tüm mülkler / iadeler / açıklamalar doldurulmalıdır) ve tüm özel / yerel şeyler gelecekteki referans için ne yaptıklarını açıklamak için bir astar alır (özel / yerel jeneratör tarafından yoksayılır).

— Evan Plaice

7

Belgelerle başlamak klasik şelale modelidir ve bu modelle ilişkili tüm tuzaklara sahiptir. Genel olarak, belgelerin sayısı arttıkça gereksinimler değiştiğinde daha fazla güncelleme yapmanız gerekir. Kullanıcı belgelerinden başlamanın bir yararı, daha erken geri bildirim (ve dolayısıyla değişiklikler) alabilmenizdir. Ancak deneyimler çoğu insanın belgeleri zihinsel olarak eylemlerle eşlemede kötü olduğunu göstermektedir. Bunun yerine, insanların yazılımı gerçekten kullanmasına ve geri bildirimde bulunmasına izin veren prototipler kullanıyoruz.

"Önce dokümantasyon" ile ilgili bir varyasyon okuryazar programlamadır . Programcıların bakış açısından programın ne yapacağına dair bir açıklama yazarak başlayın. Düzenlenene kadar ince ayar yapmaya devam edin. Voila, okuryazar bir program.

Kesinlikle! Değişim olur. Dokümantasyon çürükleri. Kod en gerçek dokümantasyon şeklidir.

— Zachary Scott

3

Kişisel olarak, şeylerin akışını göstermek için basit modelleme yapmak için diyagramlar (UML gibi) kullanmayı daha iyi buluyorum. Bu, şeyleri kelimelerle belgelemekten çok daha hızlıdır ve doğru yapılırsa açıklayıcı olabilir. Tam Dokümantasyon yapmakta tereddüt ederdim çünkü kişisel olarak üzerinde çalıştığım ve programlama sürecinde değişmeyen bir projem olmadı.

DÜZENLEME: Bazı belgeler uzun süre devam ederken yapılmalıdır. Bu, tüm belgelerin daha sonra yapılmasını kolaylaştırır.

— Kenneth
kaynak

3

Joshua Bloch, "İşyerinde Kodlayıcılar" kitabındaki röportajında bu noktayı tartışıyor.

Daha ortodoks ve akademik görüşlerin aksine, düşüncelerinizi ayarlamak için bir şeyler önerir (belki orada kendiniz okudunuz mu?): Belgeleri yazmadan önce sistemden ne istediğinizi anlamanız ve daha "gerçek bir " duygu. Bu amaçla arayüzlerin bir kısmını ve bunları kullanan bazı istemci kodlarını tasarlar.

En önemli şey ne inşa etmeye çalıştığınızı bilmektir: hangi sorunu çözmeye çalışıyorsunuz. İhtiyaç analizinin önemi göz ardı edilemez. “Oh, evet, ihtiyaç analizi; müşterinize gidersiniz, 'Neye ihtiyacınız var?' Size söylüyor ve işiniz bitti. ”

Hiçbir şey gerçeğin ötesinde olamaz. Bu sadece bir müzakere değil, aynı zamanda bir anlayış sürecidir. Birçok müşteri size bir sorun anlatmaz; size bir çözüm söyleyecekler. Bir müşteri, örneğin, “Bu sisteme aşağıdaki 17 özellik için destek eklemenizi istiyorum. O zaman sormalısın, 'Neden? Sistem ile ne yapacaksınız? Bunun nasıl gelişmesini bekliyorsunuz? '' Müşterinin yazılım için gerçekten neye ihtiyacı olduğunu anlayana kadar ileri geri gidersiniz. Bunlar kullanım durumlarıdır.

Bu aşamada yapabileceğiniz en önemli şey, iyi bir dizi kullanım vakası oluşturmaktır. Bunu elde ettikten sonra, olası herhangi bir çözümü ölçebileceğiniz bir karşılaştırmaya sahipsiniz. Sağa makul bir şekilde yaklaşmak için çok zaman harcarsanız sorun değil, çünkü yanlış anlarsanız zaten ölüsünüz demektir. Sürecin geri kalanı, boşuna bir egzersiz olacaktır.

Yapabileceğiniz en kötü şey - ve bunun olduğunu gördüm - bir grup akıllı adamı altı ay boyunca çalışmak için bir odaya sokup ne olduklarını gerçekten anlamadan önce 247 sayfalık bir sistem özelliği yazmanızdır. inşa etmeye çalışıyor. Çünkü altı ay sonra, işe yaramayabilecek çok kesin olarak belirlenmiş bir sisteme sahip olacaklar. Ve sık sık diyorlar ki, “Spesifikasyona o kadar çok yatırım yaptık ki onu inşa etmeliyiz.” Böylece işe yaramaz sistemi inşa ederler ve asla kullanılmazlar. Ve bu korkunç. Kullanım durumunuz yoksa, şeyi inşa edersiniz ve sonra çok basit bir şey yapmaya çalışırsınız ve “Aman tanrım, bir XML belgesi almak ve yazdırmak gibi çok basit bir şey yapmak kodu.” Ve bu korkunç bir şey.

- Joshua Bloch, Peter Seibel'in " İşyerinde Kodlayıcılar: Programlama Ustası Üzerine Düşünceler" konulu röportajdan

Zaten bu satırlar boyunca düşünüyorsanız, kitabı tutabilir ve tüm röportajı okuyabilirsiniz. Dediğim gibi, o her zaman çok aydınlatıcıdır.

— DPM
kaynak

Bu iyi bir tavsiye, ancak iyi dokümantasyon API'nın kullanımını içerir.

— Frank Hileman

Kayıt için, düzenlemeyi takdir ederken, bu teklifin düşündüğüm şey olmayabilir. Teğetsel olarak ilişkili ve daha yüksek düzeyde veya gereksinimler aşamasıyla ilişkili gibi görünüyor. Belgeleri yazmadan önce, doğru arabirim hakkında kaba bir fikir edinmek için arabirimi kullanacak istemci kodunu yazmaya başlayacağını ve ilk önce gelmesi gereken (bu bence sezgisel karşı taraf) olduğunu söyledi. herhangi bir düşük seviyeli tasarım dokümanı yazmadan önce. Tabii bu cevabı yazarken teklifi bulamamak benim hatam.

— DPM

1

Bazı insanlar daha da ileri gidip bir şirketin tamamen geri çalışması gerektiğini belirtiyorlar, bu yüzden

Basın bültenini yazın
SSS yazın
Müşteri deneyimini tanımlayın
Kullanım Kılavuzunu Yazın
Programlamaya başla

Bkz. Http://www.allthingsdistributed.com/2006/11/working_backwards.html

— asmaier
kaynak

1

İlk olarak tüm kod belgelerini yazmak muhtemelen aşırıdır ve şelale yöntemini hatırlatır. Ancak, daha pragmatik bir yaklaşımın önce README'yi yazdığını gördüm . İşte nedeni:

README yok değil projenizin her detayını belgelemek. Bunun yerine, genellikle aşağıdaki bilgileri içerir:

Açıklama : kısa "satış konuşması". Okuyucuya neden okumaya devam etmeleri gerektiğini söyleyin.
Kısa örnekler : açıklamayı desteklemek için kısa kod parçacıkları veya ekran görüntüleri.
Hızlı başlangıç : nasıl başlayacağınız , talimatları nasıl yükleyeceğiniz ve daha fazla örnek.
Ek belgeler : tüm dokümanlara bağlantılar ve daha fazla bilgi.
Proje organizasyonu : yazarlar kimler, nasıl katkıda bulunulur, hatalar nasıl dosyalanır.
Yasal bildirimler : lisans, telif hakkı ve diğer yasal ayrıntılar.

"Satış konuşması" nı önceden yazmak beni bu projenin neden var olması gerektiği ve geliştiricilerin niçin kullanması gerektiği konusunda çok net olmaya itiyor. Sadece projeyi tanımlamak için tam cümleler yazma eylemi genellikle projeyi daha iyi hale getirir: daha iyi anlar, yeni fikirler geliştirir ve olası sorunları ortaya çıkarırsınız. Aynı zamanda büyük bir önceliklendirme aracıdır: "satış konuşması" ndaki her şey bir zorunluluktur!

"Hızlı örnekler" ve "hızlı başlangıç kılavuzu" beni temel kullanım durumlarını kullanıcının bakış açısından düşünmeye zorluyor. Bunu, herhangi bir kod yazmadan önce - uygulama ayrıntılarında ve sıkı son tarihlerde bataklıktan önce - yapmanın çok daha temiz API ve tasarımlara yol açtığını buldum. Unutmayın: programlar insanların okuması için ve sadece tesadüfi olarak makinelerin çalışması için yazılmalıdır ( SICP ).

"Daha fazla dokümantasyon" da, daha sonra yapılacak ayrıntılı dokümantasyona ihtiyaç duyan parçaların bir taslağını oluşturuyorum. "Proje organizasyonu" proje ve kodlama uygulamaları üzerinde kimin çalışacağını anlamama izin veriyor. "Yasal uyarılar" ... iyi, bunları da yoldan çekebilir.

Bu temel README'yi yerleştirdikten sonra, tartışma, tasarım incelemeleri, işi bölme ve proje planlama için yararlı bir belgeniz olur. Proje üzerinde çalışırken, hala yolda olduğunuzdan emin olmak için sık sık README'ye danışın. Ayrıca, gittikçe README'yi ve "diğer belgeleri" kademeli olarak güncellemek, tüm belgelerinizin kod tamamlandığında yapılacağı anlamına gelir ;

Daha fazla bilgi için aşağıdakilere göz atın:

— Yevgeniy Brikman
kaynak

0

Neden sınıfların nasıl etkileşime girdiğini düşünmek istemiyorsun? Bu neden kötü bir şey? Aslında sınıfların ne olduğunu bile bilmeden etkileşimleri düşünüyorum. Böylece sınıflar kendilerini tanımlarlar.

— daldırmak
kaynak

0

Kodu yazmadan önce ne yapmayı planladığınız konusunda bir fikriniz olmalıdır. Sorun her zaman kodladığınız şeyi yazdıklarınızla nasıl eşzamanlı tutmanızdır? Bazıları denemeyin, diğerleri ilk belgeleri unutun ve yorumları takip edin. Elbette kod her zaman kanonik kaynaktır. Daha sonra sorun, kodun daha sonra gelenler veya kodu kullanan kişiler için ne yaptığını belgelemeye değip değmeyeceği haline gelir. Herkes bir işlevin ne yaptığını anlayabilir. Yazarın işi, birisinin bir saat içinde neyin çözebileceğini 5 dakikada anlamasına yardımcı olmaktır. Deltaları toplayın ve yolunuzu belirleyin.

— SnoopDougieDoug
kaynak