Her kod tabanındaki TODO’ların aslında ne kadar eski olduğunu öğrenin

Bir yılı aşkın süredir kullanılan herhangi bir kod tabanını açın ve TODO kelimesini aratın. Onlarca sonuçla karşılaşacaksınız. Peki bu notlardan birine şu soruyu sorsanız ne cevap alırdınız:

Bu ne zamandır burada?

Muhtemelen cevap veremeyeceksiniz. Yalnızca // TODO: validate the amount before charging gibi bir yorumla karşılaşacaksınız ve bunun ne zaman eklendiği, kim tarafından yazıldığı ya da şirketten ayrılan bir ekip üyesinin 2021 yılındaki notu mu olduğu hakkında hiçbir fikriniz olmayacak. Zamanla bu notlar, "bir ara bakarım" seviyesinden, dokunulmaktan korkulan kalıcı teknik borçlara dönüşüyor.

Oysa git kayıtlarında bu bilgiler zaten var. git blame komutu, hangi satırın kime ait olduğunu ve ne zaman eklendiğini biliyor. Ancak geliştiriciler, her satırı tek tek incelemekle uğraşmadıkları için bu notlar göz ardı ediliyor.

İşte tam da bu noktada devreye todoage giriyor. Bu basit, bağımlılık gerektirmeyen CLI aracı, tüm kod tabanınızdaki TODO, FIXME, HACK gibi notları tarıyor, git blame ile yaşlarını ve yazarlarını belirliyor ve en eskilerden başlayarak sıralıyor.

Eski ve gözden kaçan notları görünür kılmak

Araç, TODO, FIXME, HACK, XXX ya da BUG gibi yaygın markerları otomatik olarak tarıyor ve her birini git blame komutuyla analiz ediyor. Sonuçlar, en eski olandan başlayarak aşağıdaki gibi bir çıktıyla sunuluyor:

AGE TAG  LOCATION          AUTHOR   TEXT
418d  FIXME  src/auth/session.js:71  Alice Dev  refresh tokens before they expire
402d  TODO   src/billing/charge.js:12  Alice Dev  validate the amount before charging
311d  HACK   src/api/proxy.ts:88    Bob Maintainer  works around the upstream 1.4 bug
9d    TODO   src/ui/cart.tsx:140   Carol    wire up the empty-cart state

summary: 4 markers · 3 older than 90d

90 günden eski olan satırlar kırmızı olarak vurgulanıyor. Böylece örneğin fatura işlemlerine dair 402 günlük bir TODO’nun varlığı, artık görmezden gelinemeyecek kadar önemli hale geliyor.

Neden tickgit ya da todo-tree kullanmıyoruz?

Bu fikrin ilk kez ortaya atıldığı söylenemez. Ancak ne yazık ki bu alanda kullanıma hazır, güvenilir bir araç bulunmuyordu.

tickgit (324 yıldız) adlı araç, TODO’ların yaşını ve yazarını belirleme vaadinde bulunmuş, ancak 2020 yılından beri geliştirilmeyen bir projeye dönüşmüştü. VS Code’un todo-tree eklentisi ise editör içinde görünürlük sağlamak için oldukça kullanışlı, ancak CLI üzerinden kullanılan ve CI ortamlarında JSON raporu ya da build engelleme gibi senaryolara uygun bir çözüm sunmuyordu.

todoage, bu boşluğu doldurmak üzere tasarlandı: komut satırından çalıştırılabilen, CI dostu ve yaş ile yazar bilgilerini sunan bir araç olarak geliştirildi.

Build sürecini teknik borçtan korumak

Geliştiricilerin günlük kullanımında tercih ettiği komut ise şu şekilde:

# Çeyrekten eski TODO varsa CI’ı başarısız kıl
npx todoage --max-age 90d --fail-on-stale

Bu komut, eğer kod tabanında 90 günden eski bir TODO varsa 0 yerine 1 koduyla çıkış yapıyor. Bu şekilde teknik borçlar, birer mezar taşı olmaktan çıkıp belirli bir son tarihe sahip oluyor. --max-age parametresi, gün cinsinden (90d) ya da hafta (12w), ay (6m) ya da yıl (1y) olarak da kullanılabiliyor.

Ayrıca kullanışlı birkaç diğer komut da mevcut:

# Yalnızca Alice’in yazdığı FIXME’leri göster
todoage --tags FIXME --author alice

# JSON çıktısını dashboard’a ya da Slack botuna gönder
todoage --json | jq '.items[] | select(.stale)'

Yanlış alarmlardan kaçınmak

Basit bir grep -i todo komutu, todomvc, fixme_helper gibi kelimeleri ya da düz metin içindeki "todo" ifadelerini de yakalayabiliyor. todoage ise yalnızca gerçek yorum satırlarında bulunan, büyük harfle yazılmış markerları (TODO, FIXME gibi) tespit ediyor ve yalnızca //, #, /* */, <!-- -->, --, ; ya da yıldız (*) ile başlayan satırları dikkate alıyor. Bu sayede yanlış alarmlardan kaçınılıyor ve rapor güvenilir kalıyor.

Eğer proje bir git deposunda değilse, araç yine de tüm markerları listeleyebiliyor. Ancak yaş ve yazar bilgileri ? olarak gösteriliyor.

Kurulum ve kullanım

Araç, hem Node.js hem de Python için kullanılabilir şekilde tasarlandı. Dünyadaki kodların yaklaşık yarısı Node.js’le yazıldığı için, ilk tercih genellikle aşağıdaki gibi oluyor:

npx todoage  # Node.js — bağımlılık gerektirmez

Python kullanıcıları içinse alternatif bir kurulum yöntemi bulunuyor:

pipx run todoage  # Python — salt standart kütüphane kullanıyor

Her iki versiyon da aynı girdi ve çıktı vektörleriyle test edildiği için, sonuçlar tamamen aynı şekilde görüntüleniyor. Hangi çalışma ortamınızda hangi araç varsa onu tercih edebilirsiniz.

Tasarım felsefesi: Basitlik ve güvenilirlik

• Tek saf çekirdek, iki çalıştırma ortamı: scanLine, ageDays ve isStale gibi fonksiyonlar saf fonksiyonlar olarak tasarlandı. Girdi/çıktı, saat ya da git işlemleri gibi yan etkilerden arındırılmış durumda. Her iki versiyon da aynı girdi tablosunu kullanıyor ve bu sayede çıktılar birebir aynı oluyor.

• Yaş hesaplamaları tarih nesnelerine bağlı değil: Yaş hesaplamaları, milisaniye cinsinden veriye dayanıyor ve tam günlere çevriliyor. Zaman dilimi ya da tarihsel değişikliklerden etkilenmeyen, deterministik bir yapıya sahip.

• Salt okuma ve durumdan bağımsız: Araç yalnızca git blame yapıyor, çıktı veriyor ve sonlanıyor. Hiçbir şekilde önbellek, konfigürasyon dosyası ya da kod tabanına herhangi bir değişiklik yapmıyor. Gerektiğinde npx ya da pipx komutuyla çalıştırıp unutabiliyorsunuz.

Denemeye ne dersiniz?

Projenizdeki en eski TODO’yu bulmak için todoage’yi kullanabilirsiniz. Araç MIT lisansı altında yayınlanmış durumda ve oldukça hafif bir yapıya sahip. Eğer aracı denerseniz ya da en eski TODO’nuzu bulursanız, yazarına bildirmeyi unutmayın. Sonuçta, iki yıldır sürekli göz ardı ettiğiniz o TODO’yu temizlemenin bir bahanesi daha kalmayacak.