Diğer ortamlar hakkında bilgim yok ama konu büyük olduğunda (genellikle açık kaynak kodlu) başkalarının yazdığı PHP projeleriyse, phpXRef mutlak bir hayat kurtarıcı (özellikle de dokümanı çevrimiçi yerleştirir ve Google endeksleyebilirse).
En kötü şekilde yorumlanmış bir proje bile, en azından olayların nerede tanımlandıklarını ve nerede kullanıldıklarını (örneğin yeniden yapılanma yapılırken) bulmama yardımcı olabilir.
İyi yorum yapıldığında, sonuçta elde edilen sayfalar kod temeli için mükemmel bir İncil'e yakın oluşturur (yine de kullanımlarım için).
Dahası, tercih ettiğim IDE benim için yorumlamanın yaklaşık% 75'ini yapan yorum bloğunu (eğer yazarsam / ** yazıyorsam) otomatik olarak oluşturacaktır. Yaptığım şeyi diğer insanlara (ve gelecekteki benimle) açıklamak zorunda kalmamdan dolayı, kodlayıcı ömrüm boyunca taahhüt etmekten kaçındığım aptalca şeyler şaşırtıcı. Doktor üreticisi için yorumum bu yöntemden daha büyük olduğunda, bu genellikle yeterli kahve almadığım ve biraz daha sert düşünmek isteyebileceğim anlamına gelir.
Bu kendi kendine aynı yorum blokları, satır içi tamamlama "yardım" metnini de oluşturur; böylece işlev çağrısı yazarken tam olarak ne olduğunu (diğer kodlayıcılar tarafından) görebiliyorum. Bu benim için muazzam bir verimlilik artışıdır (özellikle, diğer bazı yararlı geliştiricilerin "iyilik uğruna X yap / yapmayın") yazdığı ender durumlarda.
Karmaşık (ve genellikle kötü adlandırılmış) PHP projelerinde belirtilen girdi türlerinin ve daha az kullanılan yöntemlerde argüman sırasının belirtilmesinin ne kadar yararlı olduğunu vurgulayamıyorum. Kendi kodumla bile, bir çağda dokunmadığım bir şey için hangi argümanları belirttiğimi her zaman hatırlayamıyorum.
Bir örnekte, tekrarlayan sorunların kaynağının, önceki geliştiricilere kötü yansıyan bir nedenden ötürü, bazı işlevlerin ve hatta sabitlerin çok sayıda yerde tanımlandığı (yani "eğlence" için tutarsızlık derecesiyle) olduğu anlamına geliyordu. . Projeden uzaklaşmanın işareti buydu.
Katılmadan önce başlayan daha büyük projelerde, hangi geliştiricinin (sınıf dosyasını bir ad ve e-posta ile etiketlediklerini varsayarak) sınıfı oluşturduğunu ve doğru geliştiriciyi bulup konuşabilmenin son derece yararlı olduğunu görebiliyorum.
Otomatik görev listeleri - @todo etiketinin kullanılması (kendimi çalıştığım türdeki projelerde yaygın olarak kullanılır), belgelerin daha fazla çalışma gerektiren şeyleri (veya eksik olduğu kabul edilen özellikleri) izleyebileceği anlamına gelir. Yine IDE'm bunun izini sürüyor ve tek başıma dikkatimi ilk önce neye dikkat etmesi gerektiği konusunda iyi bir rehber olarak görüyor.
Son olarak (ve benim için çok önemli) bazılarının (çok okunan) kodlayıcıların değişiklik yaptığı ve dokümantasyon görevlileri ile konuşmadığı zaman güncel tutmaya çalıştığı önemsiz olmayan yükü kaldırır.
Yani, nedenleri şunlardır:
- Daha sonraki geliştiricilere zaman kazandırmak,
- Nerede fonksiyonların çağrıldığını (ve tanımlanır) takip etmek,
- Aptal kodlamanın farkına varmak,
- Bir şeylerin eksik olduğu zaman (bir başkasının işaret ettiği gibi) bulmak,
- Yeniden yapılandırmayı basitleştirme (asla eğlenceli değil)
- (Pek çok durumda) geliştiricinin ne yapmaya çalıştığı hakkında bir fikir edinmek (bazı notlar bıraktığını varsayarak).
- Proje birden fazla lisansın devam etmesi için yeterince karmaşıksa (eğlenceli değil) Hangi lisansların belirli bir bölüm için geçerli olduğunu hızla görebilirim. Kuşkusuz, bu bir yan bonus.
- Proje dosyası hakkında kiminle konuşacağınız hakkında bir fikir edinmek
- Otomatik görev listeleri
Ayrıca sivri saçlı patronları bir düğmeye dokunarak mutlu etmenin değerini küçümsemeyin.
Kısacası "otomatik dokümantasyon yorumları" kodlama alışkanlıklarım için hayati öneme sahip. Bunun eksik olduğunu düşünen pek çok kişi olduğundan eminim ama tam olarak ne dediğimi bilen adil bir kaç insan olduğundan da eminim. PhpXRef'i (ve en sevdiğim IDE'yi) keşfetmeden önce nasıl hayatta kaldığımı bilmiyorum.