17

Sınırlamalar, sorun giderme ve SSS

Bilinen sınırlar, yaygın sorunlar ve çözümleri

5 dk okuma4 bölüm

Bilinen sınırlamalar

Analiz

  • Diller: yalnızca JavaScript/TypeScript (.js .jsx .mjs .cjs .ts .tsx) ve Python (.py). Diğer dosyalar yok sayılır ve satırları analiz edilen satır olarak sayılmaz.
  • Python sezgiseldir. Tam bir ayrıştırıcı değil, girinti ve kalıplar kullanır. Karmaşıklık ve iç içelik yaklaşıktır; iç içelik derinliği class/def düzeylerini içerir. Koda benzeyen çok satırlı dizeler onu yanıltabilir.
  • Tip bilgisi yok. detectUnusedCode (JS/TS) yalnızca aynı dosyada bir kez kullanılan adları bulur; dışa aktarmaları veya diğer dosyaları izlemez.
  • Sezgisel kurallar: requireErrorHandling, requireSingleResponsibility ve requireDocumentationForComplexCode doğaları gereği yanlış pozitif üretebilir.
  • Satır içi susturma yorumu yok (// eslint-disable gibi). Kuralı ayarlayın veya yolu hariç tutun.
  • Bir depoda tüm diller için aynı kurallar.
  • 1 MB'tan büyük dosyalar HEAD taramasında atlanır.
  • Glob kalıpları !, {a,b} veya [abc] desteklemez. .gitignore desteği elden gelen en iyi şekildedir (yalnızca kök dosya, olumsuzlamalar yok sayılır).

Atama

  • Pencere: analiz edilen commit'lerden önce eklenen ihlaller existing olur ve kimseye yazılmaz. Tam kapsama için daha geniş bir pencere kullanın.
  • Dosyalar arası tekrarlar mevcut kodda bulunur, ama commit yürüyüşü yalnızca dosya içi tekrarları görür; bu yüzden dosyalar arası kopyalar existing olarak görünür ve kimseye yazılmaz.
  • Yeniden adlandırmalar asıl yazarla bağlantıyı koparır: ihlaller, yeniden adlandıran commit tarafından eklenmiş (düşük güven, yazılmaz) olarak görünür ve bu commit gösterilen toplamlarında "fixed" kredisi de alır.
  • Kopyalar, kopyalayanın yazdığı yeni kod olarak ele alınır.
  • Birleştirme commit'leri atlanır; bir birleştirme commit'i içinde yapılan çakışma çözümü düzenlemeleri atanmaz.
  • Squash merge / rebase her şeyi sıkıştırılmış commit'in yazarına atar.
  • Eşli programlama / ortak yazarlar: yalnızca commit yazarı kullanılır; Co-authored-by satırları yok sayılır.

Puanlama

  • Puan kural setine ve projeye görelidir. Farklı kural setlerinden veya depolardan gelen puanlar karşılaştırılamaz.
  • Küçük örneklemler proje ortalamasına doğru büzülür; bu kasıtlıdır, ama yeni bir geliştiricinin puanının kendisinden çok proje hakkında bilgi verdiği anlamına gelir.
  • scoring.severityWeights şu anda puanları değiştirmez (kuralın severity değerini kullanın).

Yapılandırma

  • VS Code eklentisinde birkaç VS Code ayarı, varsayılan değerlerinde bile yapılandırma dosyasını geçersiz kılar; bkz. 10 — Öncelik.
  • Yerel geçersiz kılma dosyası doğrulanmaz.
  • Çok köklü çalışma alanları: yalnızca ilk klasör analiz edilir.

Sorumlu kullanım

CleanLens insanları değil, kodu ölçer. Puanları bir ekiple paylaşmadan önce:

  • puanı alt puanlar, güven, katkı ve kural setiyle birlikte gösterin;
  • insufficient / provisional puanları karşılaştırmayın;
  • bazı işlerin (incelemeler, tasarım, mentorluk, altyapı, diğer diller) onun için görünmez olduğunu unutmayın;
  • tek başına bir performans değerlendirmesi olarak değil, nerede iyileştirme yapılacağını bulmak için kullanın.

Sorun giderme

"This project is not a Git repository."

Deponun kökünü (.git içeren klasörü) açın veya CLI'a verin: cleanlens /path/to/repo. VS Code'da yalnızca ilk çalışma alanı klasörü kullanılır.

"The repository has no commits."

En az bir kez commit atın. Atama commit'lere dayanır.

".clean-code-tracker.json is invalid: …"

Listelenen hataları okuyun. Yaygın nedenler: "version" değeri 1 değil; kural kimliğinde yazım hatası; low|medium|high|critical yerine "error" gibi bir önem değeri; yorumlar veya sonda virgül (dosya katı JSON olmalıdır).

"No .clean-code-tracker.json found; using default rules."

Yalnızca bir uyarıdır. CleanLens: Initialize Project çalıştırın veya JavaScript ön ayarını kullanmak için yok sayın.

Herkes "existing" gösteriyor, kimse ihlal eklememiş

  • Commit penceresi çok küçük veya çok yeni: --full-history (CLI) veya cleanlens.analysis.maxCommits: 0 (VS Code) deneyin.
  • Sığ klon (CI'da yaygın): fetch-depth: 0 kullanın.
  • İhlallerin çoğu dosyalar arası tekrar (atanamaz, yukarıya bakın).

Bir kişi iki kez görünüyor

Bir developers girdisi veya bir .mailmap satırı ekleyin. Bkz. 11 — Özelleştirme kılavuzu §5.

İki farklı kişi tek kişi olarak birleştirilmiş

Bir adı, daraltılmış bir adı veya bir e-posta tanıtıcısını paylaşıyorlar. mergeSameNameAuthors: false ayarlayın (VS Code'da ayarı da) ve gerçek birleştirmeleri açıkça listeleyin.

Bir geliştiricide "— (no analysed code)" görünüyor

Pencere içinde analiz edilebilir dosyalarda eklenmiş satırı yok (örn. yalnızca doküman, yapılandırma veya kilit dosyaları ya da yalnızca eski commit'ler). Bu, kusursuz puanla aynı şey değildir.

Herkesin puanı çok düşük (veya çok yüksek)

Kalibre edin: önce en gürültülü kuralları bulun, sonra herkes için düşük olan kategorinin ölçeğini ayarlayın. Bkz. 11 — Özelleştirme kılavuzu §11.

Yapılandırma dosyasında bir ayarı değiştirdim ama eklenti yok sayıyor

Bazı VS Code ayarları dosyayı geçersiz kılar (analysis.maxCommits, scoring.minLinesForRanking, hariç tutma bayrakları, mergeSameNameAuthors). Bunları VS Code ayarlarında da ayarlayın.

Analiz yavaş

Önbelleği açık tutun; dışarıdan alınmış ve üretilmiş kodu hariç tutun; günlük kullanım için daha küçük bir pencere kullanın. Bkz. 09 — Önbellek ve performans.

Kuralları değiştirdikten sonra sonuçlar eski görünüyor

Olmamalı: her kural/hariç tutma/puanlama değişikliği önbelleği geçersiz kılar. Analizör kaynak kodunu değiştirdiyseniz ENGINE_VERSION değerini artırın veya --no-cache / cleanlens.cache.enabled: false ile çalıştırın ya da commits-*.json önbellek dosyalarını silin.

Hariç tuttuğum bir dosyada altı çizili uyarılar var

Canlı tanılar hariç tutma listesini uygulamaz. cleanlens.liveDiagnostics ayarını kapatın veya yok sayın; raporu etkilemezler.

Eklenti yeni bir pencerede hiçbir şey yapmıyor

Çalışma alanının güvenilir olduğunu kontrol edin (Kısıtlı Mod eklentiyi devre dışı bırakır).

SSS

CleanLens kodumu herhangi bir yere gönderiyor mu? Hayır. git çalıştırır ve dosyaları yerel olarak okur. Ağ yok, telemetri yok. Bkz. PRIVACY.md.

Kodumu değiştiriyor mu? Hayır. Deponuza yazdığı tek dosya .clean-code-tracker.json'dur ve yalnızca Initialize Project işlemini onayladıktan sonra.

Puanım neden bir ekip arkadaşımın çalıştırmasından farklı? Farklı yapılandırma (yerel geçersiz kılma, VS Code ayarları, ön ayar), farklı bir commit penceresi veya farklı bir klon derinliği. İki rapordaki analysisConfigHash ve analyzedCommits değerlerini karşılaştırın.

"Yeni ihlaller" neden şu anda koddaki ihlallerimin sayısından büyük? "Yeni" tarihsel bir sayıdır: pencerede eklediğiniz her şeyi, daha sonra (sizin veya başkalarının) düzelttikleri dahil sayar.

Katkı neden puanın parçası değil? Hacmi kaliteye karıştırmak, daha temiz kod yerine daha çok kod yazmayı ödüllendirirdi. Bilerek yan yana gösterilirler.

Bunun yerine ESLint / Ruff sonuçlarını kullanabilir miyim? Bugün değil. source alanı gelecekteki entegrasyon için eslint, ruff ve pylint değerlerini ayırır.

Bir monorepo'nun yalnızca bir klasörünü analiz edebilir miyim? Geri kalanını exclude kalıplarıyla hariç tutun. Commit yürüyüşü yine deponun geçmişinde çalışır ama hariç tutulan yolları atlar.

Dokümanların Arapça veya Türkçe sürümü var mı? Evet. Bu dokümantasyon Arapça (ar/) ve Türkçe (tr/) olarak mevcuttur; web sitesi kendi diline uyan sürümü gösterir. Ürün sayfası da Arapça olarak mevcuttur (README.ar.md).