Katı yazım kullanırken docblock typehints gereksiz mi?

Yaklaşık on yıldır gelişen oldukça büyük bir özel kod tabanım var. Ben phpDocumentor kullanmıyorum ama docblock bölümleri kullanmak açık kaynak projelerinde oldukça standart haline geldiğinden ben de depomda tüm genel yöntemler için docblock yazma benimsemiştir. Çoğu blok, tüm parametreler ve dönüş türü için küçük bir açıklama ve yazım karakterleri içerir.

Statik analizin gelişiyle, bu daktilolar tutarsızlıkları ve olası hataları bulmama yardımcı oldu. Son zamanlarda tüm kod tabanını (Şimdi PHP7.2 üzerinde çalışıyor) dönüştürdüm ve PHP'nin typehints'lerini kullanarak tüm parametreleri ve tip değerlerini mümkün olduğunca döndürdüm. Ve şimdi merak ediyorum ... Bu docblock daktiloları gereksiz değil mi? Tüm docblock'ları sürekli değişen kodla senkronize tutmak için biraz çalışma ister ve yeni bilgi eklemedikleri için bunları tamamen kaldırmanın daha iyi olup olmadığını merak ediyorum.

Bir yandan, gereksiz olsa bile belgelerin kaldırılması kötü gelir. Diğerinde, gerçekten tip ipucu olan Do-Not-Repeat-Yourself prensibi günlük tip ipucu şeylerini kırmak gibi hissediyorum.

Kodda bulunabilecek bilgiler yorumlarda çoğaltılmamalıdır.

En iyi ihtimalle onları senkronize tutmak zahmetsizdir. Büyük olasılıkla, sonunda senkronizasyondan çıkacaklar. Bu noktada, sadece kafa karıştırıcıdır.

DocBlock eşdeğerine statik olarak yazılmış dillerde bakarsanız (örn. Java, C #), doc yorumlarının tür bilgisi içermediğini göreceksiniz. Bu PHP kodunuzda olduğu gibi, kesinlikle takım elbise izlemenizi tavsiye ederim. Elbette, tür ipucunun uygulanamadığı durumlarda, yorum hala en iyi alternatifinizdir.

Bu PHP ile ilgili değildir, ancak yinelenen tür bilgisi, tür dolaylı olarak çıkarıldığında (örn. Haskell) anlamlı olabilir.

Evet, phb 7 ile docblocks gereksiz hale geldi.

Kodlamada çoğu zaman okumak için harcanır, bu yüzden aynı şeyi iki kez okumak zorunda kalmak üretkenliğinizi etkiler. Dahası, aslında önemli yorumları kaçırmayı kolaylaştırır.

Ben belirli türdeki bir dizi ipucu yazmak istediğiniz durumlar dışında, artık bilgilendirme kısmı yazmayın (örn @return int[]ya @param SomeStatus[] $statusList) ya da ben yöntemi, parametrelerin veya dönüş değeri hakkında bir yorum eklemek istediğinizde. Eğer bir docblock varsa bir docblock alle parametreleri ve dönüş türleri yoksa tetikleyen phpstorm denetimini devre dışı bırakmak önemli buldum.

Kod ve dokümantasyon genellikle farklı kitlelere sahiptir: dokümantasyon bu fonksiyonun kullanıcıları içindir . Türleri anlamak için koda bakmaları gerekmemelidir. Bu nedenle, belgeler türler dahil gerekli tüm bilgileri içermelidir.

Bazı sistemlerde, tür koddan alınabileceğinden belgelerde bir parametre türü belirtmek gerekli değildir. PHPDoc böyle bir sistem değildir. Bunun yerine, @parametikettir belgelenmiş olduğunu

Sağlandığında ne beklendiğini gösteren bir tür içermelidir ZORUNLU

PHPDoc, belge türü ipuçlarını kod türü ipuçlarına göre kontrol edeceğinden, “tüm docblock'ları sürekli değişen kodla senkronize tutmak için biraz çalışma” biraz azaltılmıştır. Bu bir tür linting / statik analizdir, bu nedenle dokümantasyon oluşturma sürecinizi otomatik test hattınızın bir parçası haline getirin.

Kendinize sormak isteyebileceğiniz başka bir soru, bu işlevlerin “sürekli değiştiğinde” neden bu ayrıntıda belgelendiğidir. Her zamanki motivasyon, arayüzlerinizin HTML referans kılavuzunu oluşturmaktır. Ancak, dokümantasyon hiçbir zaman bir IDE dışında okunmazsa veya dokümantasyonun mantıklı olduğu sabit arayüzlere sahip değilseniz, ayrıntılı doktor blokları gereksiz veya hatta yanıltıcıdır. Kararlı bir tasarıma ulaşıncaya kadar yalnızca bir özet yazmak ve tam belgeleri ertelemek daha iyi olabilir.