Bunlardan üçünü kullanmayı düşünmelisiniz.

Değil ancak, belgelerinize aşırı karmaşık deneyin: zorlaşıyor bunu güncel tutmak için, daha büyük olasılıkla o bakımsız olacaktır. IMHO, yeni bir programcı için bir kod temeli tanıtmak için minimum bir kodlama kılavuz (Macar notasyonu kullanan?, Derslere nasıl aramak, sizin değişkenleri aramak nasıl) ve phpdoc olduğunu. Kodunuzu ağır üçüncü parti kütüphaneleri ve büyük bir yapılandırma dosyasını kullanan varsa, bir çıplak, yeni bir makine üzerinde kod çalışma yapmak için adımları kapsayan küçük bir PDF yazmak.

Eğer Birim testleri kullanıyorsanız, çok, bu belge hatırlıyorum.

Hatta bu verilen, yeni bir kodlayıcı için kod tabanını terk sonra sık sık telefon görüşmeleri bekliyoruz. Ne mantıklı ve sizin için açık görünüyor muhtemel yeni adam için değil.

Dokümantasyon iyi - ama bir rehber olarak düşünüyorum. Bu programlamayı öğretmek için yazılmış olmamalı ve kolayca güncel yazılı bir belge olmamalıdır.

Ben yeni bir proje katılmak zaman ben sürekli ihtiyaç var, bir şey kod bulunur ve nasıl erişmek için nerede bilmektir. Bir gelişme işleyen veya evreleme çevreye kod satırları eşleşen önceki geliştiricilerin "desen" deneme ve keşfetme hızla kapıyı açar.

Ben bir arayüz küçük tweaks yapabilir, o zaman fındık kırık ettik ve verileri doğru geriye doğru yoluma işe başlayabilirsiniz.

Ama sonra çok az veya hiç belgelere sahip tahta projeler geliyor alışkınım. Herkes bu konuda rahat.

Projenin API'leri varsa o zaman muhtemelen diğerlerine ek vb örnek kullanımını, örnekler sunmak istiyorum.

(Ben yeniyim) neredeyse tamamen sadece, diğer programcı çalışmalarının ürünü olan orta büyüklükte bir kod temeli için kod. Biz API phpdoc yorumlardan otomatik güzelleştiren belgeleri ve sürüm-kontrol en iyi uygulama metin dosyaları var. Ben her ikisi de bu kadar vermek istiyorum: daha kapsamlı sıralı yorumlar ve otomatik test çeşit.

Ben genellikle yeni özellikler oluşturmak için API belgelerine iyi bulmak, ancak gerçekten inline yorumlar tarafından iyi izah edilebilir hata, aşağı avcılık için özellikle yararlı değildir.

Yani benim kendi çalışmalarında ben satır kod dokunmak öncesi açıklamalarda yeni kod davranışları bırakmaya çalışın. Ben de Test Driven Design taşımak istiyorum, ama gerçekten henüz o noktaya gelmedim.

Ve evet, ben bir yetkili kodlayıcı değilim, ama kod temeli ve kod çoğu başkası tarafından oluşturulan gerçeği büyüklüğü ve karmaşıklığı ben sık sık hataların potansiyel kaynaklarına açıklama için ona gitmek zorunda anlamına gelir. Eğer gerçekten hareket ettik sonra kod temeli üzerinde yaşayan yapma yatırım Yani eğer bir kaynak eğer gibi kendinizi kullanılabilir hale düşünün.

Documentative onlarla gelebilir kodu tarih ve potential web-interface taahhüt için ben gerekli düşünün son bir şey, git (veya cıva, ya da diğer bazı DVCS) 'dir.