PHP Atribute’leri Belgelerinizi Geliştirmenize Yardımcı Olabilir, Ancak Kurtaramazlar

PHP attribütleri, belgelemeyi sağlama açısından yararlı bir araçtır; ancak tek başına zayıf bir belgeleme stratejisidir. Kısa versiyonu bu.

Çekici yanı belirgin. Attributelar, kodun yanında bulunur. Yapılandırılmış, makine tarafından okunabilir ve uygulama sırasında göz ardı edilmesi zordur. Laravel ve PHP ekipleri için API’ler, politikalar, komutlar veya dahili çerçeveler geliştirenler için belge kaymasıyla ilgili mükemmel bir çözüm gibi görünmektedir.

Ancak bu doğru değildir.

Attribütler, kodun yanındaki meta verileri yakalamada mükemmeldir. Ancak amaç, görev değişimi, iş akışı ve okuyucu bağlamını açıklamada zayıftır. Onları tüm belgeleme sistemi olarak kullanırsanız, genellikle teknik olarak doldurulmuş, ancak editoryal olarak işe yaramaz bir referans çıktısı ile sonuçlanırsınız.

Önerim basit: attribütleri kaynak katmanı olarak kullanın, bitmiş belgeler olarak değil. Daha güçlü bir belgeleme sistemini beslediğinde en iyi şekilde çalışırlar; bu sistem yapı, anlatım ve insan yargısını içerir.

Attribütlerin gerçekten iyi olduğu alanlar

PHP attribütleri, aktarıcı metin için değil, yapılandırılmış meta veriler için geliştirilmiştir. PHP belgesi, bunları sınıflara, yöntemlere, özelliklere, parametrelere ve daha fazlasına eklenmiş, yansıma yoluyla erişilebilen makine tarafından okunabilir meta veriler olarak tanımlar: PHP attribütleri genel bakış.

Bu durum, kodun zaten kesin olarak bildiği şeylerde onları çok iyi bir şekilde kullanılabilir hale getirir:

• route-level metadata
• validation or schema hints
• authorization intent
• serialization rules
• OpenAPI alanı ve yanıt tanımları
• komut imzaları veya işleyici kayıtları

Başka bir deyişle, attribütler belgeleme değeri deklare edici ve yerel olduğunda parlayacaktır.

Temel bir örnek, temiz görünür:

use OpenApi\Attributes as OA;
use App\Http\Resources\UserResource;
use Illuminate\Http\Request;

#[OA\Get(
    path: '/api/users/{user}',
    summary: 'Fetch a single user',
    tags: []
)]
#[OA\Parameter(name: 'user', in: 'path', required: true, schema: new OA\Schema(type: 'integer'))]
#[OA\Response(
    response: 200,
    description: ,
    content: new OA\JsonContent(ref: UserResource::class)
)]
public function show(Request $request, int $user)
{
    // ...
}

Bu, attribütlerin iyi bir kullanımını gösterir çünkü meta veri kod yüzeyine sıkı sıkıya bağlıdır. Route şekli, parametre yeri ve temel yanıt sözleşmesi, işleyiciye yakın olmalıdır. Endpoint değiştiğinde, attribüt de onunla değişmelidir.

Bu nedenle, swagger-php gibi araçlar, artık attribütleri yoğun bir şekilde kullanıyor. Bu belgeler, attribütleri birinci sınıf belgeleme yolu olarak ele alır ve zaten anotasyon modelini yerine attribütlere taşımaya yönelmektedir: swagger-php ve attribüt referansı.

Böylece, attribütlerin desteklediği durum geçerlidir. Onlar, uygulama detayları ile makine tarafından okunabilir referans verileri arasındaki kaymayı azaltır.

Attribütle yönlendirilen belgelerin bir tuzak haline gelmesi

Problem, ekiplerin yapılandırılmış meta veriyi yararlı belgeleme ile karıştırması ile başlar.

Oluşturulan bir referans teknik olarak tamam olabilir, ancak yine de okuyucusunu yanıltabilir.

Bu genellikle üç öngörülebilir şekilde gerçekleşir.

1. Belgeler yerel ancak anlamlı hale gelir

Attribütler, ne olduğunu söylemekte harikadır. Ama neden önemli olduğunu söylemekte kötü bir performans sergilerler.

Oluşturulan bir API sayfası, bir endpoint’in status, page ve sort kabul ettiğini belirtebilir ve yine de geliştiricilerin gerçekten önemsediği sorulara asla yanıt vermez:

• Hangi filtreler kararlı API sözleşmeleridir yoksa kolaylık yardımcıları mıdır?
• Hangi kombinasyonlar yavaş veya önerilmeyenlerdir?
• Hangi varsayılanlar iş açısından kritik öneme sahiptir?
• Hangi hata durumları, istemcilerin etrafında tasarlaması gerekenlerle ilgilidir?
• Bu endpoint ne zaman kullanılmamalıdır?

Attribütler bu sorulara doğal olarak yanıt vermez çünkü bu yanıtlar yerel gerçekler değildir. Bu, editoryal açıklamalardır.

2. Referans, atlanmalarla yalan söylemeye başlar

Ekipler, oluşturulan belgelere aşırı güvenme eğilimindedir çünkü resmi görünürler. Ancak temiz bir oluşturulmuş sayfa, ciddi boşlukları gizleyebilir:

• örnekler eksik
• yanıt anlamları yetersiz belirtilmiş
• yetkilendirme davranışı ima edilmiştir, ancak belirtilmemiştir
• sayfalandırma kenar durumları mevcut değildir
• iş kuralları hizmet kodunda kalır, belgelenmiş sözleşme içinde yer almaz

Bu, kaymanın tehlikeli bir versiyonudur. Belgeler görünüşte eski değildir. Onlar plausible incomplete‘dir, bu daha kötüdür çünkü insanlar daha uzun süre onlara güvenir.

3. Attribütler birikirken düzenlenmeleri zordur

Attribüt eklemek ucuz görünüyor, bu yüzden ekipler her yere ekliyor. Bu başlangıçta iyi. Sonra kod tabanı gürültülü hale geliyor.

Bir kontrolör yöntemi, yönlendirme meta verilerini, OpenAPI meta verilerini, güvenlik meta verilerini, yanıt meta verilerini ve dahili çerçeve meta verilerini tek bir yığının içinde taşır. Bu noktada, kendi kendine belgeleyen bir kod yaratmadınız; bir meta veri duvarı oluşturmuş oldunuz.

O duvarın iki maliyeti vardır:

• geliştiriciler dikkatlice okumayı bırakır
• oluşturulan belgeler aynı dikkatsizlikten miras alır

Çıktı yine de doğrulanabilir. Bu, iletmediği anlamına gelmez.

Gerçek karşılaştırma: attribütler vs. editoryal belgeler

Faydalı karşılaştırma, attribütler ile kimseyi karşılaştırmak değildir. Asıl karşılaştırma attribütler sadece belgeleri ile attribütler ve editoryal belge katmanı arasındadır.

Attribütler yalnızca belgelemeleri kazanır:

• koda yakınlık
• makine okunabilirlik
• üretim hızı
• belirgin şema kayması riski olmaması
• daha iyi araç otomasyonu

Editoryal belgeler kazanır:

• karar verme bağlamı
• niyetle örnekler
• okuyucuları hata modlarından uyarmak
• endpoint’ler veya modüller arasındaki desenleri açıklamak
• yeni geliştiricilerin sistemi nasıl kullanması gerektiğini anlamalarına yardımcı olmak

Bu nedenlerle, attribütler hem bir kısayol hem de bir kayma tuzağıdır.

Yalnızca elle yaparsanız belgeler kayar çünkü insanlar unuturlar. Sadece attribüt odaklı kalırsanız, belgeler kayar çünkü oluşturulan çıktı yalnızca jeneratörün görebildiği parçaları yakalar.

En iyi sistemler işi böler.

• Attribütler, kod üzerinde kalması gereken yapılandırılmış gerçeği sahiplenir.
• Üretilen referanslar o gerçeği tutarlı bir şekilde açığa çıkarır.
• Editoryal belgeler sistemin nasıl kullanılacağını açıklar.

Bu, genel olarak Laravel uygulamalarında da işe yarayan bir kalıptır. Route tanımlamaları mimari belgeler değildir. Doğrulama kuralları, yeni üyelik belgeleri değildir. Kaynak sınıfları, ürün rehberliği değildir. Bunlar daha büyük bir anlayış için girdilerdir.

Belgeleme aynı şekilde tasarlanmalıdır.

Attribütlerin Laravel kod tabanlarında en çok yardımcı olduğu yerler

Laravel ekipleri, attribütlerden en iyi sonuçları, bunları sözleşme yüzeylerinde kullanarak elde ederler; evrensel bir yazım sistemi olarak değil.

İyi hedefler şunlardır:

• API endpoint metadata
• istek ve yanıt şeması eşlemesi
• politika veya izin kaydı
• olay, dinleyici veya komut keşfi
• halka yansıma zaten mevcutsa dahili paket kancaları

Kötü hedefler, genellikle açıklamanın deklare edilmesinden daha önemli olduğu yerlerdir.

Örneğin, bu makul bir attribüt şeklidir çünkü yerel gerçeği yakalar:

#[RequiresPermission('users.view')]
#[AuditAction('user.viewed')]
#[CacheTtl(seconds: 60)]
final class ShowUserAction
{
    public function __invoke(int $userId): UserData
    {
        // ...
    }
}

Bu attribütler, çerçeveniz ya da araçlarınıza somut bir şey iletir. Ayrıca oluşturulan dahili referans materyalinde de görünür hale getirilebilir. Ancak yine de daha büyük sorulara yanıt vermez.

• users.view neden users.list‘den ayrılmıştır?
• Önbellek neden sadece 60 saniyedir?
• Hangi kullanıcı durumları kasıtlı olarak gizlenmiştir?
• Audit garantileri, aşağıdaki sistemler tarafından ne beklenmelidir?

Bu yanıtlar, yalnızca insana yönelik belgelerde yer almalıdır; büyüyen bir attribüt yükünde değil.

Yararlı bir kural

Eğer bir gerçek:

• kodla güçlendirilmişse,
• yansıma ile incelenebiliyorsa,
• ve yapılandırılmış meta veri olarak anlamlıysa,

burada bir attribüt için iyi bir yerdir.

Eğer bir gerçek:

• gerekçe,
• örnekler,
• sıralama,
• alışveriş tartışması,
• veya yanlış kullanıma dair uyarılar gerektiriyorsa,

o zaman yalnızca abstrakt belgelerde olmamalıdır.

O çizgi, ekipleri kodu bir belgeleme çöplüğüne dönüştürme hatasından kurtarır.

Oluşturulan belgeleri nasıl dürüst tutabilirsiniz

Başarısızlık durumu, attribütleri kullanmamaktan değil, oluşturulan bir çıktının yanında bir editoryal sözleşme ile birlikte gelmemesindendir.

En kolay çözüm, jeneratörlerin bitmiş çalışmaları üretmesini ummak yerine küçük bir belgeleme mimarisi tanımlamaktır.

1. Hangi attribütlerin sahip olmasına izin verileceğini belirleyin

Açık olun. Her ekibin kendi doktrinini icat etmesine izin vermeyin.

Örneğin:

• attribütler yönlendirme, şema, yetkilendirme ve yanıt meta verisini sahiplenir
• markdown belgeleri, eğitimler, iş akışları, taşınma notları ve karar kurallarını sahiplenecektir
• değişiklik kayıtları sürüm deltasını üstlenecektir
• örnekler, test edilmiş fixturelar veya örnek isteklerde yaşar

Bu, açık görünse de çoğu ekip bunu atlar. Sonra belgelerin neden yarısının kontrolörlerde, diğer yarısının ise Confluence mezarlarında yaşadığını merak ederler.

2. Referansları oluşturun, sonra giriş noktalarını düzenleyin

Oluşturulmuş bir OpenAPI sayfası, bir geliştirici deneyimi değildir. Bu, bir referans eseridir.

Hala şunlara benzer özenli giriş noktalarına ihtiyacınız var:

• “Buradan başlayın” rehberleri
• yaygın iş akışları
• yetkilendirme ayarları
• sayfalama ve oran-limit davranışı
• sürümleme kuralları
• gerçek istemci kullanımını yansıtan örnekler

Oluşturulan referans, bu sayfaları desteklemeli, yerini almamalıdır.

3. Örnekleri birinci sınıf belge olarak ele alın

Attribütle yönlendirilen sistemlerde genellikle zayıf noktadırlar. Şemaları iyi yakalarlar, ancak örnekleri kötü yakalarlar.

Eğer belgeleme jeneratörünüz örnekleri destekliyorsa, bunları aktif şekilde kullanın. Eğer desteklemiyorsa, test edilmiş örnekleri kod tabanının yakınında tutun ve bunları editoryal belgelere çekin. Teknik olarak doğru bir şema, gerçekçi bir örnek olmadan çok daha az faydalıdır.

4. Attribütleri dekorasyon gibi değil, API yüzeyi gibi inceleyin

Attribüt değişiklikleri dış davranışı etkiliyorsa sözleşme değişikliği olarak ele alınmalıdır. Bu, kod incelemesinin şu soruları sorması gerektiği anlamına gelir:

• Yanıt sözleşmesi değişti mi?
• Durum kodu hala doğru mu?
• Nullable alanlar hala doğru mu?
• Özet, yalnızca uygulama detaylarını değil, gerçek kullanımın özetini mi yansıtıyor?

Eğer gözden geçirenler attribütleri zararsız bir sözdizimi süsü gibi ele alırsa, belgeler yine de bozulur.

5. Önemli kayma kontrolleri ekleyin

En iyi attribüt bazlı belgeleme setupları, oluşturulan çıktı ve taahhütlü eserler arasında farklılıklar olduğunda başarısız olur.

Pratikte bu, şunları içerir:

• CI’de OpenAPI’nin oluşturulması
• oluşturulan özellik dosyalarının karşılaştırılması
• belgelendirilmemiş kırıcı değişikliklerin reddedilmesi
• örneklerin mümkünse test edilmesi

Otomasyon iyi bir metin oluşturamaz; ancak kötü referans kaymasının sessizce geçmesine engel olabilir.

Önerim

Laravel veya daha geniş bir PHP ekibi için üç katmanlı bir model kullanmayı öneririm.

Katman 1: Strukturlu kaynak gerçeği için attribütler

Yerel, makine okunabilir ve doğrudan koda bağlı meta veriler için PHP attribütlerini kullanın.

Bu, yönlendirme sözleşmeleri, şemalar, yetkilendirme ipuçları ve diğer iknacı yüzey detaylarını içerir.

Katman 2: tutarlılık için üretilmiş referans

Bu kaynak gerçeklerinden API referans eserleri üretmek için swagger-php gibi araçları kullanın. Jeneratörlerin endpoint belgelerinin tekrarıyla başa çıkmalarını sağlayın, böylece insanlar kararlı sözleşme verilerini yeniden yazmaya zaman harcamazlar.

Katman 3: Anlam için editoryal belgeler

Bizim sistemin nasıl kullanıldığını açıklayan kısa, fikri belgeler yazın:

• hangi endpoint’lerin en önemli olduğu
• yaygın entegrasyon akışları
• iş sorunları
• performans tuzakları
• taşınma notları
• gerçekliği yansıtan örnekler

Bu son katman, ekiplerin atlamaya çalıştığı katmandır. Aynı zamanda “teknik olarak belgelenmiş” ile “gerçekten kullanılabilir” arasındaki ayrımı oluşturan katmandır.

Pratik öneri

PHP attribütleri, belge ile ilgili meta veriler için kesinlikle kullanmaya değer. Onlar, yapılandırılmış gerçekleri uygulamaya yakın tutarak kaymanın en can sıkıcı olanlarından birini azaltır. Özellikle Laravel ekipleri için, bu gerçek bir kazançtır.

Ancak, belge tasarımının yerini almazlar.

Geliştiricilerin güvenebileceği belgeler istiyorsanız, attribütleri referans gerçeği tutmak için kullanın, üretimi bu gerçeği tutarlı tutmak için kullanın ve editoryal yazmayı, sistemin pratikte nasıl kullanılacağını açıklamak için kullanın. Bu, çalışan dengenin sağlanısını oluşturur.

Karar kuralı basittir: Attribütler, kodun güvenle iddia edebileceği şeyleri belgelemelidir; insanlar ise okuyucuların hala anlamaya ihtiyacı olan şeyleri belgelemelidir.

Tüm makaleyi QCode’da okuyun: https://qcode.in/php-attributes-as-documentation-useful-shortcut-or-drift-trap/