PHPDoc ayrinti bu değer daha fazla sorun var mı?

1 Cevap php

Ben bugün ilk defa PHPDoc kullanarak çalıştı ve hızlı bir şekilde sorun koştu.

Değişken bildirimlerini her 1 hattı için, ben yorumların en az 5 çizgiler vardı. Örnek:

/**
 * Holds path the remote server
 * @name ...
 * @global ...
 */
 $myvar = ...

Tabii ki, rüşvet güzel - ama bu bir 60-satır dosya içine 10 hat config dosyası döner. Doldurmak için beni sonsuza kadar sürer, ve ben henüz ikna olmuş değilim bu ekler basit bir-liner üzerinde fazla.

Bu da benim iş akışında bir ilginçlik atar. Ben köklü değişiklikler yapmak için ihtiyacınız olana kadar tüm ince ve iyi. Benim iyi belgelenmiş doc-blokları ile, aniden artık benim kod refactor var, ama bütün bu sıkıcı ayrıntıları yeniden yazmak gerekir. Demek için sonuna kadar beklemek? HAH! Sonra belgeleri asla olmayacak.

Hepsinin üstüne - bu benim kod ortasında C tarzı / ** / yorumum beni zorlar. Bu talep üzerine büyük bloklar açıklama yeteneğini şeritler beri bu gelişim sırasında beni delirtiyor. , Aralık, s / ^ / # /: Şimdi kod aa büyük bloğunu açıklama, ben bir şey çekmek için gibi gerek daha sonra geri almak. Sıkıcı!

Uzun lafın kısası - Ben, PHPDoc seviyorum ben iyi belgelenmiş kod seviyorum - ama kodun her bir satır için yapılan yorumlar 5 satır far too much! olduğunu. Ben eksik özellikler var mı? Bu ortak bir sorun var mı?

1 Cevap

Overkill olsun veya olmasın uygulamanın kullanım amacı büyük ölçüde bağlıdır. Eğer tek bir şirket ya da grup tarafından sadece kullanılacak bir uygulama yazıyorsanız, muhtemelen her değişkenin kapsamlı belgelerine gerek yoktur.

Örneğin, şu anda ben oldukça geniş bir kod tabanı ile bir proje üzerinde çalışıyorum ama çok az geliştiriciler (şimdilik, sadece bana). Sınıflar ve yöntemler: ben iki şey için PHPDoc blokları ekliyorum. Her şey için, ama değil ayrıntılı PHPDoc biçimde, sık sık comment. Bu kodun çoğu sadece şimdiye kadar üç veya dört kişi tarafından görülecektir, ve onlar ihtiyacınız olacak bilgileri kara kutu info: Ben bu yöntemi ne gönderebilirim, ne ben onu dışarı almak için bekliyoruz. Onlar özel sınıf değişkeni için ne bir Model veri değil almak için nasıl bilmek istiyorum.

Ben diğer geliştiriciler veya şirketlere dağıtmak için tasarlanmış bir uygulama yazarken, ve ben onları diğer sistemlerle benim app entegre veya onun işlevselliğini genişletmek için beklenen, ben daha kapsamlı PHPDoc kullanımı hakkında daha fazla değer bir yer olacaktır. Ayrıntı bu tür kesinlikle uzun süreli bakım sırasında kullanışlı gelebilir.

Vaka noktada, benim şimdiki proje noktada diğer sitelerden erişilebilen bir API oluşturulmasını gerektirecektir. API fazla yorum ve kod satırları daha yazılı belgelere sahip olacak bahse girebilirsiniz.

etiketler