Arayüz Standardı Dokümanda Kalırsa Uygulanmaz

Çoğu ekipte arayüz standardı bir belgede yaşar: kurallar yazılır, dosya paylaşılır, sonra kimse açmaz. Geliştiricinin koda dökerken gerçekten baktığı yer ise yandaki ekranın kaynağı ve dokümandaki ekran görüntüsüdür. Standardın tutup tutmayacağını da bu belirliyor: kural nerede duruyor, yazılan koda ne kadar yakın?

Kimse belgeyi baştan sona okumuyor

Uyum ölçümleri yapan ekiplerin ortak gözlemi şu: kural seti kısa ve net olsa bile tam uyum çıkmıyor. Geliştirici belgeyi bir ders kitabı gibi okumuyor, elindeki soruna en yakın örneği arıyor ve onu kopyalıyor. Bu yüzden dokümandaki bir ekran görüntüsü, aynı konudaki üç paragraf kuraldan daha fazla iş görüyor.

Peki bu bir disiplin sorunu mu? Sapmaların çoğu kuralı reddetmekten değil, kuralın kod yazılan anda elde olmamasından geliyor. Ekip kararı verirken belgeye dönmenin maliyeti, mevcut bir ekrandan kopyalamanın maliyetinden yüksekse sonuç baştan belli.

Bol örnek ekleyin tavsiyesinin faturası

Standart yazma rehberlerinde üç öneri neredeyse her zaman birlikte geçer: belge kısa olsun, örnek bol olsun, örnekler kurala yüzde yüz uysun. Bu üçü aynı anda tutmaz.

Bir kural belgede bir kez anlatılıp beş örnekte gösteriliyorsa, o kural değiştiğinde altı yerde düzeltme gerekir. Biri atlanırsa belge kendi kendiyle çelişir ve okuyucu hangisine uyar? Kurala değil, örneğe. Yani yanlış kalmış tek bir ekran görüntüsü, o kuralın hiç yazılmamış olmasından daha kötü sonuç verir. Örnek eklemek bedava bir iyileştirme değil, üstlenilen bir bakım borcudur.

Kendi dokümanınızda hızlı bir kontrol: içindeki ekran görüntüleri kaç sürüm önceki butonu gösteriyor?

Kuralı koda gömmek

Bir kuralı dokümanda anlatmak yerine bileşenin arayüzüne gömmeyi tercih ederim. Buton yalnızca tanımlı varyantları kabul ediyorsa, boşluklar yalnızca token ölçeğinden geliyorsa, standart dışına çıkmak yasak olmaktan çıkar ve zor hale gelir. Bu ikisi arasındaki fark büyük: yasak hatırlanmayı gerektirir, zorluk gerektirmez.

Ölçülebilir kuralların bir kısmı daha da ileri gider ve lint kuralına dönüşür. Renk değerinin doğrudan yazılması, ikon boyutunun elle girilmesi, erişilebilirlik etiketi olmayan ikon buton: bunlar derleme sırasında yakalanabilir. Yakalanabilen kuralı belgede tutmak, o kuralı gönüllü bırakmak anlamına geliyor.

Her şey koda taşınmaz elbette. Mikro metnin tonu, bir akışın modal mı ayrı sayfa mı olması, hata mesajının kullanıcıyı suçlamaması gibi kararlar yargı gerektirir ve cümleyle anlatılmak zorundadır. Dokümanın kısalabileceği yer de burası: kodun zorlayabildiği ne varsa çıkar, geriye gerçekten okunması gereken kararlar kalır.

Uyumu nasıl ölçersiniz

Geliştiricilere standarda uyup uymadıklarını sormak işe yaramıyor, çünkü çoğu uyduğunu düşünür. Daha faydalısı, üretimdeki ekranlardan rastgele bir örneklem alıp sapmaları kural kural saymak.

Çıkan tablo iki şeyi ayırır. Bir kural neredeyse her ekranda ihlal ediliyorsa sorun ekipte değildir: ya kural belirsizdir ya da onu uygulayacak bileşen yoktur. Hiç ihlal edilmeyen kurallar arasında da kimsenin karşılaşmadığı durumlar çıkar, onları silmek belgeyi kısaltmanın en risksiz yolu.

Standart, yazıldığı gün değil uygulanabildiği gün başlar. Doküman bunun sadece küçük bir parçası.