Komut Satırı Arayüzü Yönergeleri

 (clig.dev)
24 puan yazan xguru 2020-12-28 | 3 yorum | WhatsApp'ta paylaş

Geleneksel Unix ilkelerini korurken modern biçimde güncellenmiş açık kaynaklı rehber

  • CLI tasarım felsefesi

    → insan önce gelir

    → birlikte çalışan basit parçalar

    → programlar arasında tutarlılığı koru

    → yalnızca gerektiği kadar konuş (ne az ne fazla çıktı)

    → kolay keşfedilebilir olsun (kapsamlı yardım, örnekler, sıradaki komut önerileri, hata olduğunda yapılacak iş önerileri)

    → sıradan bir konuşma gibi

    → dayanıklı ol

    → kullanıcıya empati göster

    → kaos: kuralları bozman gerekiyorsa niyetini ve amacını açıkça belirt

  • CLI yönergeleri

    → temel

    ✓ komut satırı ayrıştırma kütüphanesi kullan: Go(Cobra,cli), Node(oclif), Python (Click,Typer), Ruby(TTY)

    ✓ başarıda 0, hatada 0 dışı bir kod döndür

    ✓ çıktı stdout'a

    ✓ log, hata vb. mesajlar stderr'a

    → yardım

    ✓ seçenek vermeden çalıştırıldığında yardım çıktısı göster (-h, --help)

    ✓ varsayılan olarak kısa yardım çıktısı göster

      · bu program ne yapar

  · bir veya iki çağrı örneği

  · bayrak açıklamaları (çok fazla değilse)

  · ek açıklamalar için `--help`

    ✓ -h, --help seçeneğinde tam yardım çıktısı göster

    ✓ geri bildirim/issue almak için bir kanal sun

    ✓ yardımda web sürümü dokümanına bağlantı ver

    ✓ örneklerle anlat

    ✓ örnek çoksa, bunları başka bir yerde yayınla (cheat sheet veya web sayfası)

    ✓ man sayfalarına fazla kafa yorma (pek kullanılmıyor ve Windows'ta da çalışmıyor)

    ✓ yardım uzunsa pager'a pipe et

    ✓ en sık kullanılan bayrakları ve komutları yardımın başında göster

    ✓ yardımda biçimlendirme kullan (kalın yazı)

    ✓ kullanıcı bir şeyi yanlış yaptıysa ve bunu tahmin edebiliyorsan öneri sun

    ✓ komutun pipe ile bir şey almasını bekliyorsan ve stdin etkileşimli bir terminalse, yardımı gösterip hemen çık

    → çıktı

    ✓ insanın okuyabileceği çıktı en önemlisidir

    ✓ kullanılabilirliği bozmuyorsa makinenin okuyabileceği çıktı da sun

    ✓ insanın okuyabileceği çıktı yüzünden makinenin okuyabileceği çıktı mümkün olmuyorsa, grep / awk gibi araçlarla birlikte kullanılabilmesi için --plain seçeneği ver

    ✓ --json girdisi verilirse JSON formatında çıktı ver

    ✓ başarı durumunda tercihen çıktı olmasın; gerekiyorsa kısa tut. -q seçeneğiyle gereksiz çıktıyı kapatmayı destekle

    ✓ bir durumu değiştiriyorsan, bunu kullanıcıya söyle (git push çıktısına bak)

    ✓ mevcut sistem durumunu görmeyi kolaylaştır

    ✓ kullanıcının çalıştırabileceği komutlar öner (git status'un git add / restore göstermesi gibi)

    ✓ programın iç sınırlarını aşan davranışlar açık olmalı. Kullanıcının istemediği dosyaları okumak/yazmak (cache gibi) veya uzak sunucuya bağlanmak (dosya indirmek gibi) buna dahildir

    ✓ bilgi yoğunluğunu artırmak için ASCII art kullan

    ✓ rengi amaçlı kullan. Aşırıya kaçma

    ✓ terminal değilse veya kullanıcı isterse rengi kapat

    ✓ stdout etkileşimli bir terminal değilse animasyon gösterme

    ✓ sembol/emoji yalnızca bir şeyi daha net kıldığında kullan

    ✓ varsayılan olarak, yalnızca geliştiricinin anlayacağı bilgileri çıktıya koyma

    ✓ stderr'ı log dosyası gibi kullanma (en azından varsayılan olarak değil. Ayrıntılı modda ERR, WARN gibi log seviyeleri göster)

    ✓ çok fazla metin üretiyorsan less gibi sayfalama araçları kullan

    → hata

    ✓ hataları yakala ve metni insanlar için yeniden yaz

    ✓ signal-to-noise ratio (sinyal/gürültü oranı) önemlidir. Aynı hata birden çok kez oluşursa, açıklayıcı bir başlık altında gruplayarak göster

    ✓ kullanıcının ilk olarak nereye baktığını hesaba kat

    ✓ beklenmeyen/açıklanamayan hata oluşursa, debug/trace bilgisi ver ve bu bug'ı geliştiriciye nasıl göndereceğini açıkla

    ✓ bug raporunu ek çaba olmadan gönderebilmeyi sağla. (Tüm bilgileri içeren bir URL üretip yalnızca tarayıcıya yapıştırarak raporlanabilsin)

    → argümanlar ve bayraklar

    ✓ argüman: konumsal parametre. Sıra önemlidir. cp bar foo ile cp foo bar farklıdır

    ✓ bayrak: adlandırılmış parametre. -r gibi tek harfli veya --recursive gibi uzun olabilir. Sıra genellikle önemli değildir.

      kullanıcı değeri de içerebilir. `--file foo.txt` veya `--file=foo.txt`

    ✓ argüman yerine bayrağı tercih et. Daha çok yazı yazdırır ama daha açıktır. Argüman çoksa sonradan özellik genişletmek zorlaşır

    ✓ bayrağın hem kısa hem uzun sürümü olsun. Script içinde uzun sürümü kullanmak ekstra açıklama gerektirmez

    ✓ tek harfli bayrakları yalnızca sık kullanılanlar için kullan

    ✓ basit bir işlem için birden fazla argüman almak da mümkündür

    ✓ iki veya daha fazla farklı argüman gerektiriyorsa bir şeyi yanlış yapıyor olabilirsin

    ✓ bayraklarda (zaten varsa) standart adları kullan

      `-a --all`, `-d --debug`, `-f --force`, `-h --help`, `-o --output`, `-p --port`, `-q --quiet`, `-u --user`

    ✓ varsayılanları çoğu kullanıcı için uygun olacak şekilde seç

    ✓ kullanıcı girdi gerektiren bir argüman/bayrak verdiyse ama değer gelmediyse, kullanıcıdan giriş iste

    ✓ değeri argüman/bayrakla geçmenin yolunu her zaman sun; kullanıcıyı zorunlu prompt'a mecbur bırakma

    ✓ tehlikeli bir iş yapmadan önce her zaman onay iste

    ✓ giriş veya çıkış dosya ise, - ile stdin'den okumayı veya stdout'a yazmayı destekle

      $ curl https://example.com/something.tar.gz | tar xvf -

    ✓ bayrak ek değer alabiliyorsa, none gibi özel kelimeleri kabul et. ssh -F none

    ✓ mümkünse argümanları, bayrakları ve alt komutları sıradan bağımsız yap

    ✓ hassas (parola gibi) argüman değerlerinin dosyadan verilebilmesine izin ver

    → etkileşimlilik

    ✓ prompt veya etkileşimli özellikleri yalnızca stdin etkileşimli bir terminal olduğunda kullan

    ✓ --no-input verilirse, prompt ya da herhangi bir etkileşimli özellik kullanma

    ✓ parola alırken kullanıcının yazdıklarını gösterme

    ✓ kullanıcının kolayca çıkabilmesini sağla (vim gibi yapma). Ctrl-C çalışsın. ssh, tmux gibi program çalıştırma nedeniyle Ctrl-C mümkün değilse, SSH'deki gibi ~ ile başlayan escape sequence sunduğunu açıkça göster

    → alt komutlar

    ✓ karmaşık araçlar, karmaşıklığı azaltmak için alt komut sunabilir

    ✓ ayrıca sıkı ilişkili birden çok araç varsa, bunları tek bir komutta toplayıp kullanımı kolaylaştırabilirsin

    ✓ alt komutlar arasında tutarlı ol. Aynı bayrak aynı anlama gelsin, çıktı biçimleri benzer olsun

    ✓ çok katmanlı alt komutlarda tutarlı adlandırma kullan

    ✓ kafa karıştıran veya birbirine çok benzeyen adlar kullanma. update ve upgrade gibi

    → dayanıklılık

    ✓ tüm kullanıcı girdilerini doğrula. Erken kontrol et ve anlaşılır hata göster

    ✓ hızdan çok tepki verebilirlik daha önemlidir

    ✓ uzun sürüyorsa ilerleme durumunu göster

    ✓ mümkünse işleri paralel yap. Ama bunu dikkatlice tasarla

    ✓ timeout koy

    ✓ idempotent yap. (Tekrar çalıştırılsa da sonucun değişmemesi.) Hata olduğunda shell'de yukarı oka basıp en baştan değil kaldığı yerden sürdürebilsin

    ✓ crash-only yap. Bu, idempotence'ın bir sonraki adımıdır. İş bitince temizlik yapmak gerekmiyorsa veya temizlik bir sonraki çalıştırmaya ertelenebiliyorsa, program hata/veri kesintisi halinde hemen çıkabilmelidir

    ✓ insanlar programını yanlış kullanacaktır

    → geleceğe dayanıklılık

    ✓ mümkün olduğunda değişiklikleri ekleme yoluyla yap. Eski davranışı bozup uyumluluğu kırma; yeni bayrak ekle

    ✓ ekleme yoluyla olmayan değişiklikler yapacaksan önce uyar

    ✓ insanlar için olan çıktı değişiklikleri çoğunlukla sorun değildir

    ✓ sık kullanılan bir alt komut var diye, açıkça belirtilmese bile onu çalıştıran catch-all alt komut yapma

    ✓ rastgele alt komut kısaltmalarına izin verme

    ✓ bir gün mutlaka bozulacak “zaman ayarlı bomba”lar yapma

    → sinyaller ve kontrol karakterleri

    ✓ kullanıcı Ctrl-C (INT signal) gönderirse mümkün olduğunca çabuk durdur

    ✓ kullanıcı uzun süren bir clean-up sırasında Ctrl-C'ye basarsa ilkini yok say; ikinci basışta zorla kapatmaya izin ver

      ^CGracefully stopping... (press Ctrl+C again to force)

    → yapılandırma

    ✓ XDG(X Desktop Group) spesifikasyonunu izle

    ✓ programına ait olmayan yapılandırmayı değiştiriyorsan kullanıcıdan onay al ve ne yaptığını açıkça belirt

    ✓ yapılandırma parametrelerini öncelik sırasına göre uygula

      bayraklar > shell ortam değişkenleri > proje düzeyi yapılandırma (`.env`) > kullanıcı yapılandırması > sistem yapılandırması

    → ortam değişkenleri

    ✓ ortam değişkenleri, komutun çalıştığı bağlama göre değişen davranışlar içindir

    ✓ taşınabilirliği en üst düzeye çıkarmak için ortam değişkenleri yalnızca büyük harf/rakam/alt çizgi içermeli ve rakamla başlamamalıdır

    ✓ mümkünse ortam değişkenlerinde tek satırlı değerler kullan

    ✓ yaygın kullanılan adları kullanma

    ✓ mümkünse genel amaçlı ortam değişkenlerini kontrol edip kullan

      `NO_COLOR`, `DEBUG`, `EDITOR`, `HTTP_PROXY`, `SHELL`, `TERM`, `TERMINFO`, `HOME`, `TMPDIR`, `PAGER`, `LINES` ..

    ✓ gerekirse .env'den ortam değişkenleri yükle

    ✓ yapılandırma dosyası için .env uzantısını kullanma

    → adlandırma

    ✓ adlar kısa ve akılda kalıcı kelimeler olsun

    ✓ yalnızca küçük harf kullan, - (tire) işaretini de sadece gerekirse kullan

    ✓ mümkünse kısa tut

    ✓ klavyede yazması kolay olsun

    → dağıtım

    ✓ mümkünse tek binary olarak dağıt

    ✓ kolay kaldırılabilir olsun

    → analitik

    ✓ aracın kullanım ve çökme verilerini kullanıcı onayı olmadan kendine gönderme

İlgili okumalar

3 yorum

 
jonnung 2021-01-09

Güzel içerik için teşekkürler.
 
xguru 2020-12-28

Rust ve Go'nun tek bir binary olarak iyi paketleme sağlaması sayesinde, iyi komut satırı araçlarının giderek arttığı görülüyor.

Bunları yapmak da giderek daha kolay ve daha güçlü hale geliyor.
 
xguru 2020-12-28

Kısaca çevirirken ben de çok şey öğrendim. Bitirdikten sonra bakınca... Aslında repo'nun tamamını çevirmek daha iyi olmaz mıydı diye de düşündüm. ^^;;