Bu belgeye adapte edilmiştir Jack Bradshaw’un öyküsü . Stil Yönetmelikleri Monorepo Etkili belgelendirme, sürdürülebilir kalkınmanın temel kaynağıdır; ancak ekibin büyümesinin kaçınılmazlığı, parçalanmamış ve uyumsuz bir ekip olarak belgelendirmeyi zorlaştırır; bu nedenle, katkıda bulunanlar arasında belirli bir düzeyde koordinasyon gereklidir. Bir zamanlar serbest geçişe sahip tek başına mühendisler bile, şimdi AI tarafından oluşturulan belgelendirme uyumsuzluğu ile mücadele etmek zorundadır. ben de depolamdaki belgelerin bir kısmını oluşturmak için AI kullanıyorum, ancak zamanla sonuçlarla memnun değilim; özellikle, kod tabanında tutarlılık ve tutarlılık eksikliği. Bu sorunu çözmeye yönelik ilk girişim, 13 kural içeren Genel Belgelendirme Standart Belge'nin oluşturulmasıyla sona erdi; özellikle: Belgelendirme kişisel, objektif, hassas, resmi, harfli, geçerli, sözleşmeli, ters, açıklayıcı, kesin ve açıklayıcı olmalıydı. Bu bir sanat eseriydi, kusursuz, yüce, sadece monumental başarısızlığıyla rekabet eden bir zaferdi. Amacım, AI tarafından objektif olarak doğrulanabilir ve uygulanacak belirsiz standartlar oluşturmaktı; ancak, bir sorun zamanla ortaya çıktı; özellikle, bazı gereksinimler objektif olarak doğrulanabilirken (örneğin liste biçimlendirme gibi), diğerleri doğaüstü subjektifti (kararsızlık, kesinlik vb.) ve değerlendirilmesi zordur; ayrıca, Belgeyi tamamen yeniden yazdım ve içeriği üç türde bölüyorum: standartlar (absolut ve objektif), uygulamalar (subjektif ancak belirsiz), ve yönergeler (çok subjektif ve belirsiz), yönergelere karşı ağır bir eğilime ihtiyaç duyuldu. sert kuralların yerine yüksek düzeyde rehberlik üzerine odaklanarak ve çelişkili aşırılıklar arasında bir orta alan teşvik ederek, yeni yönergeler, bilinen anti-pattern ve başarısızlık modlarını engellediğinde bireysel ifade için yeterli alan sağlar. Etiket: akıllıca bilgelik Depozito belgeleri, kod tabanına ve gerektiğinde dış kaynaklara atıfta bulunarak objektif ve gerçeğe dayalı olmalıdır; ancak, zor kazanılan deneyim biçimindeki subjektivite önemsizdir, çünkü gerçeklerin tek başına yararlı olabilmesi için bağlam eksikliği vardır ve katkıda bulunanların benzersiz deneyimlerinden / bakış açılarından kaçınmak destekleyici bir ortam yaratmaz; bu nedenle, belgelendirme objektiflik ile subjektiflik arasındaki dengeyi içermelidir. Too Academic: "FooSort, potansiyel fonksiyonları ve toplam yöntemleri kullanarak amortizasyon analizi yoluyla Henderson (1984) tarafından resmi olarak kanıtlanan O(N log N) ortalama hesaplama karmaşıklığını gösterir. empirik doğrulama, 10.000 eşit olarak dağıtılan veri kümesi üzerinde Monte Carlo simülasyonuyla gerçekleştirildi, %95 güven aralığı elde etti [0.98N log N, 1.02N log N]. Algoritmik sağlamlık peer-review edildi ve ACM Transactions'te yayımlandı (DOI:10.1145/12345)." Too Poetic: "FooSort, verileri şık bir balet gibi dans eder, elemanları uygun yerlerine şık bir şekilde dokar. Her turda verimliliği, kaosdan düzen düzen düzenlemeye yönelik karşılaştırmaların bir simfoni şimşekler." (Flowery metaforları teknik anlamı karışık) Just Right: “FooSort, O(N log N) ortalama zamanında N öğeleri sınıflandırır, bu nedenle çoğu kullanım vakası için uygundur. Bununla birlikte, şirket X’de müşterilerin yüklemeleri tipik olarak önceden sınıflandırıldığında üretim sorunlarına neden olan raporlu sıralanmış verilerde O(N2)’ye düşer. Objektiflik ve subjektiflik arasındaki denge, belgelerin doğru ve erişilebilir kalmasını sağlarken katkıda bulunan ve destekleyici bir alan yaratır. Etiket: Minimalizm ile Yeterlilik Katılımcılar, eksik belgelerin gizli maliyetlerini önlemek için yeterli bilgi içermelidir, çünkü birkaç ek paragraf (kilobit) depolama maliyeti, eksik bağlamın maliyeti (örneğin, düzeltme saatleri, üretim başarısızlıkları, tekerleğin yeniden icat edilmesi) çok daha düşüktür; ancak gereksiz ayrıntılar gerçeği gereksiz ayrıntılar altında gizlerken gereksiz ayrıntılar amacını yitirir; bu nedenle belgelendirme gereksiz bilgileri terk etmelidir. Too Minimal: "FooProvider önbellek değerleri." ( Davranış, sona erme veya bilinen sorunlar hakkında yetersiz bağlam) Too Verbose: "FooProvider içeride 16'nın başlangıç kapasitesi ve 0.75'in yük faktörü olan bir ConcurrentHashMap instantiated kullanır, bu değerler kendileri System.nanoTime()'den kaynaklanan 64-bit zaman damgasını içeren özelleştirilmiş bir CacheEntry nesnesine sarılmıştır ve ayrı bir daemon thread üzerinde çalışan bir ScheduledExecutorService tarafından tetiklenen temizleme döngüleri sırasında ters sırada geçirilen senkronize çift bağlantılı bir liste aracılığıyla uygulanan en az yeni kullanılan bir politika kullanılarak silinebilirler. Just Right: "FooProvider, 60 saniyelik TTL değerlerini bir LRU çıkarma politikasını kullanarak önbellek eder. Bu önbellek bir arka planda çalışır ve bellek kısıtlı Android cihazlarında OOM hatalarına neden olabilir." (Hayat ve bilinen sorunlar hakkında yeterli bağlam, gereksiz uygulama detayları olmadan). Minimalizm (gereksiz ayrıntılardan kaçınma) ve yeterlilik (yeterli bağlam sağlama) arasındaki denge, belgelerin aşırı uygulama ayrıntıları altında kritik bilgileri gizlemeden yararlı ve erişilebilir kalmasını sağlar. Etiket: geçmiş, şimdiki ve gelecek dengesi Belgelendirme, geleceği belgelemek, planlar değiştikçe yanlışlık riski oluşturur ve geçmişi belgelemek, geçmişi geçmiş bilgi ile karıştırır; ancak, tarihsel bağlam genellikle geçmişin tekrarlanmamasına karşılık geleceği haklı çıkarır ve gelecekteki çalışmalar için fırsatların tanınması bilinen eksiklikleri vurgulamaktadır; bu nedenle, geçmiş ve gelecek faydalı olduğunda referans edilmelidir. Too Past-Focused: "Bu yöntemin geçmiş uygulamaları standart matematik kütüphanesini kullandı. parser ile ilgili sorunlar vardı, ancak düzeltildi." (aksiyonel bağlam olmadan ilginç ayrıntılar) Too Future-Focused: "Q4'te analizi yeniden yazmayı planlıyoruz. v2.0'de bu yöntemi asinkron hale getireceğiz." (Şimdiki durum hakkında bağlamsız sözler) Just Right: "Özel bir analizci kullanılır, çünkü standart kitaplık analizcisi v1.2'de performans regresyonlarına neden oldu.Bu yöntem senkron, ancak gelecekteki bir sürümde asenkron destek eklenebilir (#123 ile izlenir)." (Şimdiki durum tarihsel bağlam ve izleme referansı ile tanınmış sınırlamalarla haklıdır). Stabilite (olduğunu belgelemek) ve bağlam (gerekli arka plan sağlamak) arasındaki denge sağlanması, belgelerin doğru ve yararlı kalmasını sağlar, aynı zamanda faydalı geçmişi korur ve bilinen kısıtlamaları kabul eder. Not: Gelecekteki planları harici izleme referanslarına bağlamak, okuyuculara takip etme ve güncellemeleri almak için bir yol sağlar. Etiket: basitlik ile hassasiyet Belgeler teknik olarak doğru ve doğru olmalıdır, çünkü belirsiz açıklamalar yanlış anlaşılmaya ve yanlış kullanımlara yol açar; ancak aşırı teknik ayrıntılar temel kavramı gizleyebilir ve okuyucuları şaşırtabilir; bu nedenle, katkıda bulunanlar gereksiz karmaşıklık olmadan kesin açıklamalar sağlamalıdır. Too Vague: "FooProvider, ihtiyaç duyduğunuz zaman nesneleri oluşturur." (Hayat hakkında teknik hassasiyet eksikliği) Ayrıca ayrıntılı: "FooProvider, aksesuar yönteminin her inisiyatifi, yeni operatör aracılığıyla toplu bellek dağılımını tetikler, böylece kendi bellek adresine sahip ayrı bir Foo örneğinin yapımına neden olur." (Aşırı teknik ayrıntılar basit davranışları gizler) Just Right: "FooProvider her çağrıda Foo'nun yeni bir örneğini oluşturur." (Daha fazla karmaşıklık olmaksızın kesin teknik açıklamalar). Doğruluk (teknik olarak doğru olmak) ve basitlik (bilinçli olmak) arasındaki denge, belgelerin, uygulama detaylarıyla okuyucuları aşırı derecede zorlamadan doğru bilgileri aktarmasını sağlar. Etiket Arşivi: formalite ile informalite Belgelendirme, güvenilirliği ve netliği koruyan profesyonel bir dil kullanmalıdır, çünkü bilgilendirici slang okuyucuları yabancılaştırabilir ve algılanan yetkiyi azaltabilir; Ancak, aşırı akademik veya resmi cümleler bilişsel engeller yaratır ve okuyucuları uzaklaştırır; bu nedenle, katkıda bulunanlar açık, standart teknik İngilizce kullanmalıdır. Too Informal: "Kotlin'in compiler oldukça serin ve sadece kodunuzu bytecode veya JVM ve şeyleri gibi farklı platformlar için ne olursa olsun dönüştürür." Too Formal: "Kotlin'in kompilasyon süreci, Java Sanal Makinesi için bytecode ve alternatif yürütme altyapıları için benzer eserler üretmekle sona erer." Just Right: "Kotlin JVM ve diğer platformlara (örneğin JS, yerli) kompile eder." Formalite (profesyonellik korumak) ve bilgilendirici (dışarıdan ulaşılabilir olmak) arasındaki denge, belgelerin genel mühendisler için erişilebilir olmasına rağmen güvenilir ve yetkili kalmasını sağlar. Etiket: Özel Grup Referansları Belgelendirme genellikle kararların ve eylemlerin arkasındaki kişileri veya ekipleri referanslamak gerektirir, çünkü atıfta sorumluluk ve bağlam sağlar; ancak kişisel adlandırmalar ("biz", "ben", "biz", vb.) belirsizdir; bu nedenle katkıda bulunanlar mümkün olduğunca belirli bireysel / grup isimleri kullanmalıdır. Çok karmaşık: "FooProvider tavsiye edilir." (Kim tarafından tavsiye edilir?) Too Vague: “Sürücüleri kaldırmaya karar verdik.” (Kimin “biz” olduğunu bilmiyoruz) Just Right: “Kernel Ekibi, çalıştırma süresi performansı için sürücüleri kaldırmaya karar verdi.” Özelleştirme (accountability ve bağlam sağlama) ve netlik arasında bir denge sağlama (birbirinden belirsiz pronounlardan kaçınma) belirli grup referansları (örneğin "The Maintainers", "The Compiler Team", "The Security Workgroup") yerine belirsiz pronounlar kullanarak net bir iletişim sağlar. istisna: Kullanıcıya (örneğin “Siz”) atıfta bulunan pronomlar kabul edilebilir (Balance Declarative ve Imperative Tone ile ilişkili). Anahtar Kelimeler: Balance Declarative and Imperative Belgelendirme, depolamanın içeriğini davranışlarını ve özelliklerini belirterek tanımlamalıdır, çünkü bu, içerdiği eserlere odaklanmaktadır; ancak, prosedürler, kılavuzlar ve kılavuzlar doğrudan okuyucuya zorunlu talimatlar ile yazıldığında daha net olabilir; bu nedenle, katkıcıların bağlamlara göre tonu eşleştirmeleri gerekir. Too Imperative: "Onu kullanmadan önce FooProvider'ı yapılandırmanız gerekir. ilk önce init() yöntemi çağırmalısınız." (referans belgelerinde komutlar) Too Declarative: " //foo:bar hedefi gerçekleştirildiğinde eserler oluşturur." (Adım adım rehberlik gerektiren bir öğretimde pasif bir açıklama) Just Right: "Referans belgeleri: FooProvider kullanmadan önce init() çağrılarak yapılandırılmalıdır. öğretici: eserleri bazel run //foo:bar çalıştırarak oluşturun." (Sistem açıklamaları için açıklama tonu, prosedür rehberliği için zorunlu tonu). Deklaratif (sistemi tanımlayan) ve zorunlu (kurucuyu yönlendiren) arasındaki denge sağlanması, belgelerin bağlamlarına uygun bilgileri sağlamasını sağlar, referans belgeleri eserlere odaklanır ve kılavuzlar açık hareket edilebilir adımlar sağlar. Etiket: güven ve alçakgönüllü Belgelendirme, içeriği iyi anladığında güvenle yazılmalıdır, çünkü gereksiz korunma otoriteyi zayıflatır ve hiçbirinin bulunmaması gerektiği yerde şüphe yaratır; ancak, gerçeğin belirsiz olduğunda aşırı ikna ile konuşmak güvenilirliğe zarar verebilir; bu nedenle, katkıda bulunanlar, bilginin sınırlarını kabul ederek ve belirsizlikleri hakkında şeffaf olmalarıyla, güvenin ve alçakgönüllülükle dengelenmelidir. Too Hesitant: "FooProvider muhtemelen iplik güvenli değildir ve çalıştırma süresi başarısızlığının küçük bir riski vardır." (Bilinen davranış hakkında gereksiz korunma) Çok güvenilir: “FooProvider kesinlikle yüksek bellek basıncı altında çalışacaktır.” Sadece Doğru: "FooProvider filtre güvenli değildir. yüksek bellek basıncı altında davranış tanımlanmamış ve test edilmemiştir." (bilinen gerçekler hakkında güvenilir, bilinmeyenler hakkında dürüst). Güven (kuruluş otoritesi) ve alçakgönüllülük (sınırları tanımak) arasındaki denge, belgelerin gereksiz şüphe yaratmadan güvenilirliğini korur. Etiket: tarafsızlıkla yargılama Katılımcılar, gerçek sorunları, sınırlamaları ve kısıtlamaları tanımlamak için yargılama yapmalıdır; Ancak, sistemleri, platformları veya katılımcıları saldırgan yargılama dili faydasızdır; bu nedenle, katılımcılar, suçlamayı veya kapsamlı olumsuz karakterizasyonlar yapmadan, gerçek açıklamalara odaklanmalıdır. Çok tarafsız: “Bu uygulama her yerde çalışır.” (hakimi eksik, gerçek kısıtlamaları görmezden gelir) Too Judgmental: "Android bu kadar çirkin bir işletim sistemidir ki bunu bile çalıştıramaz, aynı zamanda bu çirkinliği kim yazdı?" (platforma ve insanlara kişisel saldırı) Just Right: "Android cihazları yaklaşık 2012'de bu uygulamanın amaçlandığı gibi çalışmasını engelleyen bellek sınırlamalarına sahiptir. Foo uygulamasının Android'de çalışmaması." (Sonuç, spesifik, bilgilendirici ve gerçekçi açıklamalarla). Yargı (gerçek sorunları ve kısıtlamaları tanımlamak) ve tarafsızlık (kişisel saldırıları ve suçlamaları önlemek) arasındaki denge, belgelerin yargılamanın kullanımı olmadan doğru ve yararlı bilgileri sağlamasını sağlar. Etiket: saygı ile denge Katılımcılar, potansiyel zorlukları kabul ederek ve destekleyici rehberlik sunarak okuyucuyu dikkate almalıdırlar; ancak, okuyucunun zihinsel veya fiziksel yetenekleri ile ilgili iddialar ve varsayımlar, kritik bir kişiler arası sınırı aştıkları için kontraproduktif olabilir; bu nedenle, belgelendirme seçenekleri ve tavsiyeleri sunmalıdır, aynı zamanda okuyucuna kuşkusuzluktan yarar sağlamak ve kişisel değerlendirmelerden kaçınmak gerekir. Too Dismissive: "Bu davranış açıktır ve anlaşılabilir olmalıdır." (Okurun potansiyel zorluklarını dikkate almaz) Too Presumptuous: “Bu nesneyi muhtemelen karıştırıcı bulacaksınız ve sıkıştığınızda muhtemelen sorun giderme kılavuzunu okumalısınız.” Just Right: “Bu nesne, arayüz sözleşmesini tam olarak uygulamaz ve beklenmedik şekilde hatalar yapabilir. Çağrıcılar, üretime hazır bir hizmet yerine Bar kullanmak isteyebilir. Tam belgeler README’de sağlanır.” (kısıtlamaları kabul eder, seçenekler sunar, tarafsız ve saygılı kalır). Düşünce (potansiyel zorlukların tanınması) ve saygı (okuma hakkındaki varsayımlardan kaçınma) arasında bir denge oluşturmak, belgelerin kişiler arası sınırları aşmadan veya yetenekler hakkında varsayımlar yapmadan destekleyici rehberlik sağlar. Anahtar Kelime: Abstraksiyon ve Açıkçası Belgelendirme, gereksiz uygulama ayrıntılarını gizler ve anlayışa yardımcı olduğu için, sistem tasarımı ile uyumlu uygun abstraksiyonları kullanmalıdır; Ancak, anlatıcı ve renkli dil kavramları içindeki gerçeği gizleyebilir; Bu nedenle, katkıda bulunanlar, sistem davranışlarının açık ve doğrudan açıklamalarına odaklanmalıdır. Too Narrative: "Foo bir taşıyıcı kemeri gibi çalışır, kemerin üzerinde ilk Bar işlenir, sonra bir sonraki ve benzeri, kemer boş kalıncaya kadar ve operatör hiçbir şey yapacak olduğunda öğle yemeğine gider." (Metaphor anlamını gizler) Too Imperative: "Foo her Bar nesnesini bir Node olarak sarar, her biri bir sonraki / önceki düğmeye bir bağlantıya sahiptir ve bir düğmeye (markalı kök düğmeye) bir referans tutar, sonra düğümler arasındaki bağlantıları tekrarlayarak bunları eklendiği sırada işler. Just Right: "Foo bir FIFO sırası kullanarak Bar nesneleri işler ve sırası boşken boşluklar. Foo, Bar nesneleri asynkron bir şekilde işlemek için pub-sub şablonunu kullanır." (Clear, doğru abstraksiyon ile doğrudan açıklamalar). Abstraksiyon (implementasyon ayrıntılarının gizlenmesi) ve netlik (öykü ağırlığı önlemek) arasındaki denge sağlamak, belgelerin gereksiz kavramsal dolandırıcılık olmadan uygulamayı açıkça açıklamasını sağlar. Kılavuz: Bilanço Belgelendirme Boyutu ile Yakınlık Dokümantasyon, ilgili eserlerin yakınında dağıtılmalıdır, çünkü bu, okuyucuların monolitik belgeler tarafından sıkışıp kalmasını önler ve bilgileri kolayca bulmalarına yardımcı olur; Ancak, çok fazla belge üzerinde bilgi yaymak anlamı karartır ve okuyucuların bir tutarlı tabloya sahip olmamasını sağlar; bu nedenle, katkıda bulunanlar kolokasyon ile tutarlılık arasında dengelenmelidir. Too Centralized: The root repository README containing documentation for the entire repo. (Çok zor, navigasyon zor) Too Fragmented: Her paketde sadece bu paketin ayrıntılarıyla bir README, paketlerin nasıl ilişkilendikleri hakkında herhangi bir genel bakış veya bağlam yok. Just Right: Depo yapısını ve felsefesini tanıtan bir kök README, büyük paketler için daha küçük granüler READMEs ile. (toplam ve ayrıntılı olarak dengeli dağılım). Kolokasyon (bilgiyi önemli olduğu yere yakın tutmak) ve birleşiklik (birleşik bir tablo sağlamak) arasındaki denge, belgelerin aşırı derecede veya parçalanmadan erişilebilir olmasını sağlar. Not: Bir dizin belgesini aynı dizinin birden fazla dosyasına bölmek, bilgilerin doğru yerde olduğunda yardımcı olabilir, ancak belge çok büyüktür. Etiket: Uygun Belgelendirme Granüler belgelendirme (örneğin Javadoc, inline yorumlar) ilgili bileşenlere odaklanmalıdır; yüksek düzey belgelendirme (örneğin READMEs, mimari belgeleri) bileşenlerin nasıl entegre edildiğini ve birleştirildiğini ve daha geniş bir sisteme nasıl uyduğuna odaklanmalıdır. Pozitif Örnek: Javadoc, bir fonksiyonun parametrelerini, dönüş değerlerini ve kenar durumlarını açıklıyor. Negatif Örnek: Javadoc, tüm sistem mimarisini açıklıyor. Olumlu Örnek: Paketlerin nasıl etkileşime girdiğini ve genel tasarım felsefesini açıklayan README. Negatif Örnek: Her fonksiyonun iç uygulamasını açıklayan README. Bu, okuyucuların redundans veya kapsam eşleşmesi olmaksızın uygun bir abstraksiyon seviyesinde uygun bilgileri bulmalarını sağlar. Standart : Amerikan İngilizcesi Amerikan İngilizcesi kullanılması gerekir, alan sözleşmeleri başka bir şey söylemediği sürece (örneğin, bir üçüncü taraf paketinden bir Colours nesnesi referans). Etiket Arşivi: “Renk” Etiket Arşivi: “Renk” Bu, kod tabanında tutarlılık sağlar ve genel yazılım mühendisliği konvensiyonlarıyla uyumludur. Bir istisna: Belgelendirilen temel API/sistem başka bir dil kullanırsa, belgelendirme eşleşmelidir. Etiket: doğru yazım Tüm yazılar doğru olmalıdır. Etiket Arşivi: “Öneriler” Etiket Arşivi: “İstekleri” Bu, profesyonellik korur ve yanlış iletişim önler. Standart: kısaltmalardan sonra komma yok Kısaltmaların ardından komutlar atılmalıdır. Olumlu bir örnek: “etc.” Olumsuz örnek: “etc.” Bu da görsel karışıklığı azaltır. Standart: Hiçbir Ampersands “and” kelimesi ampersand sembolü “&” yerine kullanılmalıdır. Olumlu örnek: “Standartlar ve Uygulamalar” Etiket Arşivi: “Standardlar ve Uygulamalar” Bu, resmi yazma konvensiyonlarına uymaktadır ve erişilebilirliği geliştirir.
