Spatie kılavuzları üzerindeki görüşlerim: ajan becerileri

Laravel Geliştiricileri için Kılavuz

Spatie’nin paylaştığı kodlama kılavuzları üzerine birkaç yorum yapacağım. Bu yazıda PHP/Laravel kılavuzlarına odaklanacağım.

<hr/>

<blockquote>
    <p>Resmi olmayan stringler için camelCase kullanın</p>
</blockquote>

<p>Model(ler) her zaman <a href="https://www.php-fig.org/psr/psr-12/" target="_blank" rel="noopener noreferrer">PSR-12</a> kuralına uymuyor gibi görünüyor. Bu durum, örnekleri okuyarak çıkarım yapmayı gerektiriyor.</p>

<hr/>

<blockquote>
    <p>Kısa nullable notasyonu kullanın: ?string değil string|null</p>
</blockquote>

<p>Bu, PSR-12'de açıkça belirtilmiştir. Kuralın arkasındaki mantığı anlıyorum, çünkü diğer PHP işlevleri <code>null</code> belirtmek için soru işaretini kullanıyor.</p>

<p>Kendi görüşüme göre, üç veya daha fazla seçenek içeren durumlar için <code>null</code>'ın olduğu yerlerde uzun notasyonu kullanmak daha tutarlı olur.</p>

<hr/>

<blockquote>
    <p>Typed properties kullanın, docblock'ları değil</p>
</blockquote>

<p>Kod kullanarak belgeleme yapmayı destekliyorum. Bu noktada docblock'larda dizi şekilleri kullanmaya karşıyım; şekil önemliyse tür kullanmak daha mantıklı.</p>

<hr/>

<blockquote>
    <p>Tüm özellikler teşvik edilebildiğinde constructor property promotion kullanın</p>
</blockquote>

<p>Değişken argüman listesi ile birlikte, bu kıyaslama karmaşık bir hal alıyor. Değişken argüman listesi girişi daha sağlam bir şekilde geçmek için daha iyi bir yöntemdir.</p>

<hr/>

<blockquote>
    <p>Iterables'ı generics ile belgeleyin:<br/><code>/  @return Collection<int> */</code></p>
</blockquote>

<p>Eloquent model çıktısı için özel bir koleksiyon türü oluşturmak daha iyi bir yol olacaktır.</p>

<hr/>

<blockquote>
    <p>Docblock'larda sınıf isimlerini her zaman dışa aktarın; tam nitelikli isimler kullanmayın:</p>
</blockquote>

<p>Bu iyi bir tavsiye!</p>

<hr/>

<blockquote>
    <p>Hatalı durumları önce ele alın, başarı durumunu sonra</p>
</blockquote>

<p>İyi bir kural, ancak her zaman mümkün değil.</p>

<hr/>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code><span class="k">if</span> <span class="p">(</span><span class="o">!</span> <span class="nv">$user</span><span class="p">)</span> <span class="p">{</span>
        <span class="k">return</span> <span class="kc">null</span><span class="p">;</span>
    <span class="p">}</span>

    <span class="k">if</span> <span class="p">(</span><span class="o">!</span> <span class="nv">$user</span><span class="o">-&gt;</span><span class="nf">isActive</span><span class="p">())</span> <span class="p">{</span>
        <span class="k">return</span> <span class="kc">null</span><span class="p">;</span>
    <span class="p">}</span>
    </code></pre>
</div>

<p>Aynı kod bloğunda, birden fazla if'in olup olmaması iyi bir hedef olsa da, bir işlevdeki if sayısını azaltmak da önemli bir hedeftir.</p>

<hr/>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code><span class="c1">// Ternary yerine else</span>
    <span class="nv">$condition</span>
        <span class="o">?</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="nf">doSomething</span><span class="p">()</span>
        <span class="o">:</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="nf">doSomethingElse</span><span class="p">();</span>
    </code></pre>
</div>

<p>Ternary operatörünün belirtilmiş olmakla birlikte, genelde bir <code>return</code> ile bağlanmadığını belirtmek önemlidir. <code>Else</code> de kötü bir tercih değil.</p>

<hr/>

<blockquote>
    <p>Tuple notasyonu kullanın: [Controller::class, 'method']</p>
</blockquote>

<p>Bu, controller’ın genellikle constructor dependency injection içerdiğini varsayıyor, ancak metod bağımlılık enjeksiyonunu kullanmak daha iyi bir yaklaşım olabilir.</p>

<hr/>

<blockquote>
    <p>CRUD yöntemlerine bağlı kalın (index, create, store, show, edit, update, destroy)</p>
</blockquote>

<p>Bu kural, tutarlılık açısından anlaşılır. Öte yandan, bu kural çok kısıtlayıcı olabilir.</p>

<hr/>

<blockquote>
    <p>config() yardımcısını kullanın, env() kullanmaktan kaçının</p>
</blockquote>

<p>Bu harika bir kural!</p>

<hr/>

<blockquote>
    <p>Bir öğeyi işlemden geçirmeden önce çıktıyı koyun (hata ayıklamayı kolaylaştırır):</p>
</blockquote>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code><span class="nv">$items</span><span class="o">-&gt;</span><span class="nb">each</span><span class="p">(</span><span class="k">function</span> <span class="p">(</span><span class="kt">Item</span> <span class="nv">$item</span><span class="p">)</span> <span class="p">{</span>
        <span class="nv">$this</span><span class="o">-&gt;</span><span class="nf">info</span><span class="p">(</span><span class="s2">"Processing item id `</span><span class="si">{</span><span class="nv">$item</span><span class="o">-&gt;</span><span class="n">id</span><span class="si">}</span><span class="s2">`..."</span><span class="p">);</span>
        <span class="nv">$this</span><span class="o">-&gt;</span><span class="nf">processItem</span><span class="p">(</span><span class="nv">$item</span><span class="p">);</span>
    <span class="p">});</span>

    <span class="nv">$this</span><span class="o">-&gt;</span><span class="nf">comment</span><span class="p">(</span><span class="s2">"Processed </span><span class="si">{</span><span class="nv">$items</span><span class="o">-&gt;</span><span class="nb">count</span><span class="p">()</span><span class="si">}</span><span class="s2"> items."</span><span class="p">);</span>
    </code></pre>
</div>

<p>Bu, debug bilgisi eklemenin varsayılan bir yolu olduğunu varsayıyor; ancak bildiğim kadarıyla bu varsayılan değildir.</p>

<hr/>

<blockquote>
    <p>Sınıf sabitleri de PascalCase kullanır:</p>
</blockquote>

<p>Bu, <a href="https://www.php-fig.org/psr/psr-2/#a2-survey-legend" target="_blank" rel="noopener noreferrer">PSR-2</a> ile uyumlu değildir.</p>

<h2>
    <a name="conclusion" href="#conclusion">
    </a>
    Sonuç
</h2>

<p>Bir ajan yeteneği oluşturmak zordur çünkü farklı modeller bilgiye farklı şekillerde yorumlayabilir. Kılavuzlar, Spatie'nin kullandığı model(ler) ile çalışacak şekilde tasarlanmıştır, bu nedenle bazı kurallar biraz yerinde görünmeyebilir.</p>

<p>Diğer tüm kılavuzlarda olduğu gibi, bunlar da kişisel görüşlerdir ve bu nedenle birbirimizle farklı düşünebileceğimiz yerler olabilir. Ancak, ajan yeteneklerinin kişisel tercihlere göre kolayca değiştirilebilmesi güzel bir avantajdır.</p>