Birinci sınıf kütüphanemi gönderirim. Dikkat etmem gereken herhangi bir şey var mı?


12

Kariyerimdeki "Birinci Sınıf Kütüphane Yayınlandı" başarısının kilidini açmak üzere bir Web Geliştiricisiyim ve kurşunları terliyorum (bütün gece stres altındaydım). Herkesin bunun mümkün olduğunca sorunsuz gittiğinden emin olmak için herhangi bir öneri veya öneri olup olmadığını görmek için topluluk deneyimine dokunmak isterim. Dikkat etmem gereken herhangi bir özellik veya gotchas var mı? İnşa süreci hakkında beni ısırmaya gelebilecek özel bir şey var mı?

İşte buradayım:

  • Kütüphane birim testinden geçirilmiştir ve yaklaşık% 97 kod kapsamına sahiptir
  • API iyi belgelenmiştir ve intellisense desteği için xml belgeleri oluşturulmuştur
  • Genel / özel sınıf erişimcilerinin doğru ve doğru olmasını sağladım. Tüm alıcılar / pasifler için de aynı şey geçerli
  • Hata işleme, olmasını istediğim kadar zarif değil, ama son teslim tarihine karşıyım ve şu an için onun "kadar iyi" olduğunu kabul ettim
  • Kolay günlük kaydı yok. Debug.Writeline yaygın olarak kullanıldı ... Son zamanlarda bunun deneyimimin bir yansıması olduğunu öğrendim :(

Tavsiyeniz büyük beğeni topluyor!

Kütüphane rapor oluşturmak için kullanılacaktır. Standart hat - salt okunur veritabanına bağlanır, hesaplamaları gerçekleştirir, biçimlendirir ve verileri yanıt akışına verir.


Bırakan programcılardan birini doldurmak için saçak kaynağı olarak tıkandım ve bu görev bana "dişlerini kes" projesi olarak verildi. Sınıf kütüphanesi, şirketteki diğer programcıların üretim kodu yazarken kullanmaları için yayınlanacak.


2
Ayrıntılara ihtiyacınız var, nasıl serbest bırakın? Satılık sürümü? Paylaşım için açık kaynak yayınlansın mı? Üzerinde çalıştığınız bir sözleşme başına bir müşteriye mi yayınlamak istiyorsunuz? Tam zamanlı işvereniniz için bir projenin parçası olarak geliştirme organizasyonunuzun geri kalanına mı yayınlanmak istiyorsunuz? Tam zamanlı işvereniniz için müşterinin kullanılabilirliğine yeni bir ürünün v1.0 sürümünü yayınlıyor musunuz?
Jimmy Hoffa

@JimmyHoffa: sorularınıza cevaplar ekledi. Zaman ayırdığınız için teşekkürler!
Bay JavaScript

1
Nasıl çalıştığını bilmeyen kütüphanenin bir kullanıcısı olduğunuzu varsayın. Bir şey inşa etmek için kullanın. Deneyime göre bir şeyleri değiştirin / kaldırın / ekleyin. Ardından gerçek kullanıcılara bırakın ve geri bildirimlerini alın.
mike30

Çevrimdışı (ish) referans materyaline sahip olmak için Sandcastle veya başka bir doküman üreten kitaplık kullanabilirsiniz?
Jesse C. Slicer

7
Rahatlayın. Tek bir birim teste ve tek bir API belgesi satırına sahip olmak, bu sürümü zaten deneyimlerime göre "şirketteki diğer programcılar için serbest bırakılan" kodun ~% 95'inin üzerine çıkarıyor.
Carson63000

Yanıtlar:


8

API'yı kilitleme

Bir API'yi etkin bir şekilde oluşturma sanatı, yapı ile ilgili beklentileri yönetmekle ilgilidir.

API dendiğinde özellikle genel / dahili sınıfların / yöntemlerin nasıl adlandırıldığına ve erişim düzeylerinin ne olduğuna (yani özel / genel / dahili) atıfta bulunuyorum.

Kodun prime-time için tamamen hazır olmayacağından endişe ediyorsanız, her zaman başlangıçta beta olarak yayınlayabilirsiniz.

Salıverme:

  • Beta (1.0 öncesi)

    • birden fazla API kırma değişikliği içerebilir
    • sürümler arasında geriye dönük uyumluluk değişiklikleri olmayabilir
    • lehçe eksikliği olabilir
  • Resmi (1.0+)

    • API bir sonraki büyük sürüme kadar kilitlendi
    • yapılan değişiklikler geriye dönük uyumluluğu garanti etmelidir
  • Küçük (eski 1.1)

    • hata düzeltmeleri ve-veya özellik uygulamaları içerir
    • tanımlı API ekleyebilir ancak bu API'dan uzaklaşamaz

API'nın savaşla sertleştirilmesi gerektiğini düşünüyorsanız, beta olarak bir süre yayınlayın. Bu, kullanıma hazır olduğunu ancak üretim ve / veya kritik görev kodu için kullanılmaması gerektiğini gösterir.

Birçok kişi hogwash gibi numaralandırılmış sürümleme şemalarını tedavi eder, ancak etkili bir şekilde kullanıldıklarında, yapıyı düzenleyene kadar bazı kıpır kıpır oda sağlamak için kullanılabilirler.

Nasıl kullanılacağıyla ilgili varsayımlarınız yanlış

Bir şey ne kadar iyi tasarlanmış olursa olsun, insanlar kötüye kullanmanın veya alternatif bir kullanım yaratmanın bir yolunu bulacaklar.

Bunu ele almanın bir yolu, erişimcileri (örneğin, özel / genel / dahili) kullanarak uygulamanın mümkün olduğunca kilitlenmesidir, ancak hiçbir tasarım veya mühendislik, kodu kullanıcılara yayınlamak kadar size bir fikir vermez.

Kodunuzun ne kadar 'mükemmel' olabileceğini gerçekten önemli değil, kullanıcılarınız bunun olmadığını kanıtlayacak.

Bu tam bir yeniden yazma yerine mevcut bir kod temeli kullanmak her zaman daha iyi olmasının birincil nedeni olduğunu iddia ediyorum. En iyi ihtimalle tam bir yeniden yazma, şişmeyi düzeltir, ancak yeni kod tabanının orijinal kod tabanı kadar çok (ve muhtemelen daha fazla) hata içerme olasılığı yüksektir.

Senin durumunda sıfırdan savaş sertleştiriyorsun, böylece başlayabilirsin.


Kalan üslerinle örtülü gibisin. API dokümantasyonu hayati öneme sahiptir ve gelecekte değişiklikler yapıldığında istikrarın sağlanması için testler iyi olacaktır.

Kodları üretim için piyasaya sürmeden önce tutarlı bir kayıt düzeni uygulamak önemlidir, çünkü günlükleri global olarak etkinleştirmek / devre dışı bırakmak / filtrelemek için bir yol gerekir. BTW, çoğu durumda günlüğe kaydetme yalnızca bir kitaplığın içe aktarılmasını ve Debug.WriteLine () öğesinden Logging.Debug (), Logging.Info (), Logging.Error () gibi bir çağrının değiştirilmesini içerir. Kaydedicinin kendisi yalnızca yapılandırma, filtreleme ve daha geniş bir çıktı şeması yelpazesi (dosyalar, konsol vb.) İçin standart bir uygulama sağlar.

Bunun dışında, kodu çıkarmak ve kullanılan bakmak istiyorum. Hatta az sayıda kullanıcı tarafından başlatılsa bile.


1
+1 Yeniden: günlüğe kaydetme - TraceSource'u tavsiye ederim . Temel .NET kitaplıklarının bir parçası olduğu için hiçbir dış bağımlılık sunmaz ve kullanıcıların hem kod yoluyla hem de app.config dosyaları aracılığıyla dinleyici eklemelerine ve izlemeyi yapılandırmasına olanak tanır.
Dan Lyons

4

Bulduğum iki şey, yazılım yayınlamanın anahtarıdır:

  • Ne yayınladığınızı tam olarak bilin
  • Beklentileri yönetin

Geri dönüp yayınladığınızı düzeltmek ve kodunuzun hangi sorunu çözeceğini anlamak istersiniz.

Ne yayınladığını bilmek

Doğru şekilde sürümlendirdiğinizden ve imzaladığınızdan emin olun (uygunsa). Resmi olarak yayınlanan sürümle ilişkilendirilmiş kodu etiketlemek için kaynak denetiminizi kullanın. Bu, tam olarak yayınladığınız kaynak koduna geri dönebileceğiniz için hataları daha kolay tanımlamanıza yardımcı olacaktır. Ayrıca, birkaç farklı sürümünüz olduğunda satırda yardımcı olacaktır.

En son sürümü elde tutmayı ve güncellemeyi kolaylaştırmaya çalışın. Bu bir yükleyici olsun ya da sadece ortak bir paylaşıma koymak, ne sıklıkta gönderim yapacağınıza bağlıdır.

Belgeler dahil son sürümünüzü gözden geçirdiğinizden emin olun. Yazılımı serbest bırakmak ve bir şeyleri kaçırmak konusunda gergin veya heyecanlı olmak çok kolaydır.

Beklentileri yönetme

Sınırlamaları belgeleyin ve geliştiriciler için makul bir şekilde açık hale getirin. Onları bulman iyi oldu. İnsanlar genellikle yazılımınızla ilgili sınırlamaları biliyorlarsa, özellikle bunları düzeltmek için bir planınız varsa, daha fazla anlayışlı olurlar.

İyi ya da kötü, nasıl geri bildirim istediğinizi belirtin. Dahili bir proje olduğundan, herkesin ortak bir hata izleme sistemine erişimi varsa, onlardan uygun projeye karşı hata dosyalamalarını isteyin.

Gelecekte, mümkünse API'yı değiştirmekten kaçının, müşterilerinizi rahatsız etme potansiyeline sahip olan tek şey budur. İstisnaların API'nın bir parçası olduğunu unutmayın, ancak C # 'da yöntem belgelerinin bir parçası olmasalar da. Daha sonraki bir tarihte atılan istisnaları iyileştirmek mümkün olabilir , ancak son kullanıcılarla konuşmanız ve bunun ne gibi bir etkisi olacağını görmeniz gerekir.


0

Yararlı bulabileceğiniz dağıtımlar için bir kontrol listem var. Masaüstü geliştirme yapıyorum ama bunların bir kısmı çevirmeli. İşte bunlardan bazıları:

Genel:

  • Boş olmaması gereken işlev parametrelerini boş olarak kontrol edin. Bu erken başarısız olmamı sağlıyor.
  • Gereksiz yorumları ve yorum yapılmış dosyaları kaldırın. Bunlar gelecekteki çalışmalara neden olur.
  • Herhangi bir "// TODO" yorumu arayın. Bazen kendime not bırakıyorum. Bazen onları unuturum.
  • Mümkünse üretim veritabanını kullanarak kodumu test et. Bu, tüm veritabanı değişiklikleri üretim sunucusunda yerinde olmasını sağlar.
  • Bol miktarda günlük kaydı koyun. Özellikle ilk kurulum için. Aslında benim kod genellikle bu noktada bazı gelled çünkü son günlüğü kaydedin. Kaza geçirdiğiniz bir durumda olmak istemezsiniz ve kendinize "X'in şu anda değerinin ne olduğunu bilsem" dersiniz. Önceden plan yapmaya çalışın.
  • Cephelerde üçüncü taraf kütüphane çağrılarını kaydırmaya çalışın. Bu, gelecekte kütüphanelerin değiştirilmesini kolaylaştırır ve aynı zamanda bir kütüphaneden ne istediğinizi gösteren bir kontrol listesi sağlar.

Net'e özel:

  • Tek kullanımlık nesnelerde Dispose () öğesini çağırdığımdan emin olun. Kod örnekleri veya FxCop bu durumları bulmak için kullanın.
  • Tüm olay işleyicilerini düzgün şekilde kaldırdığımdan emin olun. Bu, bellek sızıntılarını önler.
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.