Belgelemenin bozulması - bununla nasıl başa çıkılır?

Önemli : Kaynak kodu dokümantasyonunda hiçbir sorun yaşamıyoruz . Bu, düzenli kod denetimine aittir ve güncel tutulur. Bizim sorunumuz geliştiricilerin dokümantasyonunda (veya isterseniz "harici"), programcılardan bir zamanlar yazılma eğiliminde olan ve genellikle geride bırakılan programcılara blog benzeri küçük ipuçları.

Programcıların belgelerini üretmek için wiki benzeri bir sistem kullanıyoruz - programcılar tarafından programcılar için yazılan makaleler, belirli bir kod parçasının nasıl çalıştığını biraz daha ayrıntılı olarak açıklıyor. Bu wiki sayfaları genellikle şunları içerir:

• API bölümleri için tasarım kararlarının ardındaki motivasyonlar (örneğin; bu çirkin şeyi yaptık çünkü bu üçüncü taraf kütüphanesi bu şekilde yapılması gereken şeyler istiyor, çünkü bu diğer kütüphane ..., çünkü ...)
• belirli ortak görevlerle nasıl başa çıktığımızın açıklaması (örneğin; uygun uygulama stillerine başvurması, kendini kayıt defteri bileşenine kaydetmesi ve diğer bileşen tarafından otomatik olarak "taranması" için bazı arayüzlerin uygulanması gereken önemsiz pop-up görüntüleme)
• iyi uygulamalar (olduğu gibi öznel, aslında bu şeyleri yazıyoruz)
• ortam konfigürasyonu, gerekli araçlar ve kurulumu

Genel olarak, öncelikle boyutu ve blog yazısı / makale benzeri doğası nedeniyle normal kod belgelerine uymayan kod yazma ile ilgili şeyler.

Sorun

Bu sistemi tanıtmak birkaç ay önce iyi bir fikir gibi görünüyordu, bugünlerde çözdüğünden daha fazla soruna neden olduğunu hissediyorum. Örneğin:

• insanlar yapmak yazma yazılar ... ama kod değişti kez wiki güncellemesi nadiren izler
• acele eden biri tarafından yazılan ve böyle bırakılan çok sayıda çizik makale
• makale talebi genellikle proje liderinden gelse de, doğruluk / kompozisyon için neredeyse hiç doğrulanmadı - bu da bazen kalitesizliğe neden oluyor

Her zamanki bozulma. Kod değişti, wiki aynı kaldı. Bir dahaki sefere birileri bilgi aradığında, genellikle bulduğu şey, eski, düşük kaliteli şeylerden ibarettir - ve ne olduğunu, bulduğu şeylerin doğru olup olmadığını ya da daha da kötü olduğunu merak ediyor. Ve yardım etmesi gereken şey, tam tersini yapıyor.

Şu anda insanlar sorunun farkında, proje lideri dahil gibi görünüyor, ama görünüşe göre hiç kimse onunla bir şey yapmaktan rahatsız görünmüyor (veya yapacak daha ilginç şeyler var).

Benim ilk düşüncem (arka arkaya birkaç kez eski "ipuçları" tarafından ısırıldı sonra) unutulmaya atmak oldu, ama bu çok aşırı olabilir varsayalım. Bazı bilgiler dikkat çekmeye ve bazen iyi okunmaya değer, ancak sorun hala aynı: "up-to-dateness" ile nasıl başa çıkıyorsunuz ? Bir şekilde kaynak koduna bağlandı mı (dosyanın güncellenmiş sürümü kontrol edildiğinde, makalenin yazarı kodu / makaleyi revize etmesi gerekebileceği konusunda bilgilendirilir)? Belirlenen kişi günlük temelde "izliyor" mu? Düzenli temizlik yapıyor musunuz?

Wiki'de çok fazla trivia belgelediğiniz anlaşılıyor.

Kod bloklarını ve koddaki yöntemleri belgeler . Çok fazla yorum yapmak zorunda kalmamak için kodunuzu kendi kendine belgelemeye çalışın. Birim testleri yazmak da yardımcı olabilir.

Wiki'de daha fazla ayrıntıya sahip tasarım kararlarını ve mimarisini belgeleyin , böylece wiki'nin sık sık değişmesi veya çok fazla çalışma yapması gerekmez. Ekibinizdeki birçok insan mimariyi zaten biliyorsa ve ekip hızla büyümiyorsa, bunları belgelemek için güçlü bir durum olmayabilir, yüz yüze genellikle en iyi bilgi aktarımıdır.

Güncel olmayan bilgileri hemen yeniden yazın veya silin , ölü kod gibi, ne kadar uzun kalırsa o kadar zorlaşır ve daha fazla birikir. Eğer vaktiniz yoksa siliniz ve makaleyi yeniden çalışma gerektiriyor olarak işaretlerseniz, sizi yavaşlatır ve yine de sürüm kontrolünde saklanır.

Yordamları bir komut dosyasında veya yükleme dosyasında otomatikleştirerek belge . Aksi takdirde bunları wiki'de saklayın, ancak birileri wiki'den her prosedürü kullandığında, makaleyi geliştirmelerini veya sürecin bölümlerini otomatikleştirmelerini isteyin.

Blog makaleleri bloglara aittir . İnsanlar kişisel görüş ve önerilerini paylaşmak isterse bunun için bir şirket blogu oluşturun. Muhtemelen makalelerinin değiştirilmesini istemiyorlar ve kimse onları değiştirmeyecek, bu yüzden wiki'yi karıştırmasına izin vermeyin.

Belgeler teslim edilebilir olarak değerlendirilmeli ve bu nedenle izlenebilirlik ve kabul kurallarına tabi olmalı ve geliştirilecek uygun süre verilmelidir.

İnsanların yazılım belgelerinin belirli bir zamanda verilmesini "beklediğini" görmek nadir değildir.

Radikal ama etkili. Birisi yeni bir modül yazdıysa ancak belgelemediyse - sorunu izleyicideki görevi yeniden açın ve gerekirse belgelenmemiş tüm kaynak kodlarının gönderilmesini önleyin. Geliştiricilerin kaynak kodu belgelerine gerektiği gibi davranmalarına izin verirseniz, parçalanmış ve güncel olmayan belge notlarıyla sonuçlanırsınız.

Son projemde en azından gerekli tüm üçüncü taraf kütüphanelerini izleme eğilimindeyiz. Birisi yeni kitaplık getiriyorsa, ancak belgelenmemişse - dokümantasyon tanıtılıncaya kadar çözümü geri alırız. Böyle radikal bir yaklaşım olmasaydı kaos olurdu. Örneğin, tecrübesiz bir geliştirici lisansı yazılım lisansımızla çakışan bir kütüphane kullanabilir.

Bir şey hızla değişiyorsa, kodun dışında tutulmamalıdır.

API bölümleri için tasarım kararlarının ardındaki motivasyonlar

Bu özellikle koda yakın tutmak için önemlidir. Aynı kaynak dosyada olduğu gibi. Bu şekilde, bir kişi dosyaya dokunduğunda yoksaymak ve harici belgelerin var olduğunu bilmeyen kişiler tarafından TheDailyWTF'ye daha az gönderme yapılmasını istemek biraz daha zor olacaktır.

Her zamanki bozulma. Kod değişti, wiki aynı kaldı.

"Yürütülebilir dokümantasyon" - birim testleri - çok faydalı hale gelir. Kod değişirse ve testler kodla birlikte değişmezse derleme kesilir. Elbette, testlerin dokümantasyon olarak yazılması biraz beceri gerektirir. Ancak harici dokümantasyon (iyi) yazmak da öyle.

Sorunla başa çıkmanın iyi bir yolu, onu sürecin bir parçası haline getirmektir. Wiki'deki ilgili sayfalara kadar kod izlemeniz varsa / buna başvuruyorsanız, bir geliştirici neyin güncellenmesi gerektiğini kolayca bulabilir. Ayrıca, wikinin güncel olduğundan emin olmak için bir kod incelemesinde gözden geçirenleri sorumlu tutun (güncelleme ile ilgili olarak).

Bunu sürecin bir parçası olarak eklemenin başka bir yolu - çevik bir model kullandığınız için, yinelemeler için planlama sürecinin bir parçası, wiki'de planlanan değişiklikleri güncellemek olabilir. Wiki daha sonra 'işlerin böyle çalışması' kaynağı olarak hizmet eder.

Bir .net dili kullanıyorsanız , XML belgelerini (// # C # 'da) alıp MSDN yardım biçimine dönüştüren ( Sandcastle )' a bakın .

Biçim açıklama, yorumlar içerir ve diğer bazı özelliklerin yanı sıra kod örnekleri de ekleyebilir. .CHM, .HsX, .MSCH ve HTML / ASP.NET biçimlerine çıktı alabilirsiniz. Asıl proje çözümünüze eklenir ve derleme sunucusunda oluşturulur. Bunu yaptık ve her sürümde bir web sitesine konuşlandırdık ve tüketiciler bunu seviyor, çünkü belgeler sürümle ilgili ve sürekli güncelleniyor.

Belgelere nelerin dahil edileceğini de belirleyebilirsiniz. Şu anda 2 projemiz var: biri sadece sözleşmeleri ve uygun kalemleri (sınıflar, numaralar vb.) İçeren harici tüketiciler için, diğeri ise özel ve dahili işaretli öğeler de dahil olmak üzere API'daki her şeyi içeren dahili geliştiriciler için.

API'yi kullanma motivasyonları ve tuhaflıkları dokümantasyonun Yorumlar bölümüne dahil edilebildiğinden, bu, kullandığımız tek doküman haline gelmiştir. Süreç çalıştığım yerde iyi çalışıyor.

İki alana odaklanırdım, 1) Kod. 2) Yok kod notları ve belge.

1) Kod.

Kendini belgelemeye çalışın. Geçmişte sık sık tavsiye edildi ama nadiren iyi açıkladı buldum, bu yüzden ...

Bu tür sahte kod yerine:

# Routine by mdd on 7/25/2012
# processes cars for sale
a=0
col = Car.all
Collection.loop |a|
 if a.stat = 'fs' then 
   a+= a.value    
   call easo 
  endif
end

Daha çok benzeyen kod yapın:

accumulating_potential_sale_revenue = 0
cars_to_check = Car.all
cars_to_check.loop |one_car|
  if one_car.sell_status == 'for_sale'
    accumulating_potential_sale_revenue+= one_car.sale_price
    call email_about_special_offer(car)
  endif
end

'Kim ne zaman ne yaptı' bilgisini izlemek için kaynak kontrolünü kullanın.

2) Kod olmayan

Bu bilgileri korumak için bir wiki ve işaretleme biçimi kullanın. İşin bir parçası olun. Yayınlayın, gönderin ve bloglayın. Eski ve yeni içerikleri incelemek için standart haftalık veya aylık bir toplantı oluşturun. Birisi bir şey sorduğunda, cevabın verildiği bir mantra yapın ... düşüncesi ile birlikte "bu, bir dahaki sefere bir kez sorulduğunda wiki'de olmalı mı?"