g u t x .com.tr İpek yolu - Çin'i anlamaya götürürüm

Google, Kod İncelemesini nasıl yapar? | Güç Projesi

Yazar | Shuai Xin xi ndoo

Editör | Tu Min

Üretildi | CSDN Blogu

Birkaç arkadaşım ve ben Google'ın bir süre önce yayınladığı Mühendislik Uygulamaları belgesini çevirdik (https: // github .com / google / eng-apps), çevrilmiş GitHub deposu: https: // github .com / xi ndoo / eng-apps-cn, yıldız eklemeye hoş geldiniz. Şu anda, çeviri yalnızca bitmiştir, çünkü çevirmenin seviyesi sınırlıdır ve gözden geçirilmesi gerekir. Ek olarak, gelecekte kesinlikle yeni içerikler Google'da yayınlanacak, katılmak için katkıya katılmak isteyen arkadaşlara hoş geldiniz ve GitHub'a yıldız eklemeye hoş geldiniz.

Bu makale, Google'ın Mühendislik Uygulamaları belgelerinin ilk bölüm Kod İnceleme Uygulama Kılavuzudur: https: // xi ndoo.github.io/eng-practices-cn/review/.

Google Kod İnceleme Kılavuzu, iki alt bölüm içerir:

Hakem Kılavuzu: https: // xi ndoo.github.io/eng-practices-cn/review/reviewer/
Geliştirici Kılavuzu: https: // xi ndoo.github.io/eng-practices-cn/review/developer/

dönem

Bazı belgelerde bazı Google dahili terminolojisi kullanılacaktır, işte bir açıklama:

CL: Sürüm kontrol yazılımına giren veya kod incelemesinden geçen değişiklikleri temsil eden "değişiklik listesi" nin kısaltması. Diğer kuruluşlar genellikle "değişiklik" veya "yama" olarak adlandırılır.
LGTM: "Bana İyi Görünüyor" un kısaltması, iyi görünüyor, çünkü gözden geçiren CL'i onayladığında söyleyecektir.

Hakem Kılavuzu

Kod İnceleme Standardı

Kod İncelemesinin temel amacı, her zaman Google kodunun zaman içinde daha sağlıklı ve daha sağlıklı olmasını sağlamaktır. Tüm Kod İnceleme araçları ve süreçleri de bunun için tasarlanmıştır.

Bunu başarmak için artıları ve eksileri tartmalıyız.

Her şeyden önce, geliştiriciler kodlarında bazı iyileştirmeler yapmalıdırlar.Eğer asla geliştirme yapmazsanız, kod tabanının genel kalitesi artmayacaktır. Ancak gözden geçiren kişi tüm değişikliklerden utanırsa, geliştirici gelecekte iyileştirme motivasyonunu kaybedecektir.

Öte yandan, kod tabanını daha da kötüleştirmemek, kod tabanının zamanla daha sağlıklı hale gelmesini sağlamak gözden geçirenin sorumluluğundadır. Bu aldatıcıdır çünkü kodun kalitesi genellikle zamanla kötüleşir, özellikle takımın açık bir zaman sınırı olduğunda ve görevi tamamlamak için bazı fırsatçı yollar kullanmaları gerektiğini düşündüklerinde.

Bununla birlikte, kod gözden geçirenler, incelemelerinin kodundan sorumludur, bu nedenle kod tabanının tutarlı ve sürdürülebilir olduğundan her zaman emin olmak isterler (diğer göstergeler için, bkz. Dikkat ne? ")

Bunlara dayanarak, beklenen Kod İnceleme standartlarımız olarak aşağıdaki yönergeleri kullanıyoruz:

Genel olarak konuşursak, kod sistemi önemli ölçüde iyileştirdiği ve normal çalıştığı sürece, mükemmel olmasa bile, gözden geçirenler bu değişikliği geçmeye meyilli olmalıdır.

Bu, tüm Kod İnceleme kılavuzlarındaki üst düzey ilkedir.

Elbette bunun bazı sınırlamaları var. Örneğin, gözden geçirenin sistemde istemediği bazı özellikler değişikliğe eklenirse, kod iyi tasarlanmış olsa bile gözden geçiren kişi bunu reddedebilir.

Kilit nokta, mükemmel kod olmaması, yalnızca daha iyi kod olmasıdır. Kod gözden geçirenler hiçbir zaman geliştiricilerin her küçük değişikliği onaylamadan önce değiştirmelerini istememeli, bunun yerine gözden geçirenler ilerlemenin ve önerilerini benimsemenin önemini tartmalıdır. Gözden geçiren, mükemmelliği değil, sürekli iyileştirmeyi takip etmelidir. Tüm sistemin sürdürülebilirliğini, okunabilirliğini ve anlaşılabilirliğini artırabilecek değişiklikler, kod mükemmel olmadığı için günler hatta haftalarca geciktirilmemelidir.

Gözden geçirenler, kod yorumlarında daha iyi fikirler önermek için her zaman kısıtlanmamalıdır. Ancak bilgi çok önemli değilse, yorumların önüne bir logo ekleyerek göz ardı edilebileceğini söyleyebilirsiniz.

Not: Bu belgede, değişiklikler sırasında kontrol etmenin tüm sistem kodunu daha da kötüleştireceğine dair hiçbir mazeret yoktur. Yapabileceğiniz tek şey acil durumda belirtilir.

Öğretici

Kod İnceleme'nin önemli bir rolü vardır, yani geliştiricilere dil, çerçeve veya genel yazılım tasarım ilkeleri hakkında bilgi verebilir. Geliştiricilerin yeni şeyler öğrenmesine yardımcı olmak için Kod İncelemesine yorum bırakmayı savunmaya değer Sonuçta, bilgi paylaşımı da sistem kodu sağlığının uzun vadeli iyileştirmesinin bir parçasıdır. Ancak, yorumunuz tamamen eğitim amaçlıysa ve bu belgede bahsedilen temel bir standart değilse, lütfen ön tarafa "Nit:" işaretini ekleyin veya bu değişiklikte ele alınması gerekmediğini açıkça belirtin.

prensip olarak

Teknoloji ve veriler, fikirlerden ve kişisel tercihlerden daha yüksektir.
Stil sorunları ile ilgili olarak, stil kılavuzu mutlak otoritedir. Stil kılavuzunda belirtilmeyen herhangi bir stil (boşluklar vb.) Kişisel tercih meselesidir. Tarz mevcut olanla tutarlı olmalıdır. Önceki bir stil yoksa yazarın stilini takip edin.
Yazılım tasarımı hiçbir zaman sadece bir kodlama stili veya kişisel tercih meselesi değildir, sadece kişisel tercihlere değil, tartılması gereken kurallara dayanır. Bazen birden fazla etkili seçenek vardır: Geliştirici (veriler veya ilkeler aracılığıyla) bu yöntemlerin eşit derecede etkili olduğunu kanıtlayabilirse, o zaman gözden geçiren yazarın tercihini kabul etmelidir, aksi takdirde yazılım tasarım standartlarına uyulmalıdır.
Kullanılacak başka bir kural yoksa, sistemin sağlığının etkilenmeyeceği garanti edildiği sürece, gözden geçiren kişi, geliştiricinin mevcut kod tabanıyla tutarlılığı sürdürmesini isteyebilir.

Kod çakışmalarını çözme

Kod İncelemesinde herhangi bir çelişki varsa, hem geliştirici hem de gözden geçiren ilk önce geliştirici kılavuzunun ve gözden geçiren kılavuzundaki diğer belgelerin içeriğine dayalı bir anlaşmaya varmaya çalışmalıdır.

Anlaşmaya varmak zor olduğunda, geliştiriciler ve gözden geçirenler Kod İnceleme yorumlarındaki çatışmaları çözmemeli, yüz yüze toplantılar düzenlemeli veya pazarlık yapacak yetkili bir kişi bulmalıdır. (Yorumlarda müzakere ederseniz, tartışmaların sonuçlarını yorumlarda kaydettiğinizden emin olun, böylece diğerleri daha sonra okuyabilir.)

Bunların hiçbiri sorunu çözmezse, sorunu çözmenin yolu yükseltilmelidir. Olağan yöntem, ekibi birlikte tartışmaya çekmek, ekip liderinin tartmasına izin vermek, kod geliştiricisinin görüşlerine başvurmak veya Yönetim Karar vermek. Geliştiriciler ve incelemeciler aynı fikirde olamayacağı için değişiklikleri orada tutmayın.

Kod incelemesi, Dikkat ne?

Not: Aşağıdaki noktaları göz önünde bulundurduğumuzda, her zaman Kod İnceleme standardını izlemeliyiz.

tasarım

Kod İncelemesindeki en önemli noktalardan biri, değişikliğin genel tasarımını kavramaktır. Değişikliğin her bir bölümünün kod etkileşimi normal mi? Değişikliğin tamamı sorumlu olduğunuz kod tabanına mı ait? Sisteminizin diğer bölümleriyle normal şekilde etkileşime giriyor mu? Şimdi tüm özelliği eklemenin doğru zamanı mı?

Özellik

Geliştirici bu değişiklikle ne yapmak istiyor? Geliştiriciler bu kodun kullanıcılarına ne gibi faydalar sağlamayı planlıyor? (Burada "kullanıcı", değişiklikten etkilenen gerçek kullanıcıları ve kodu gelecekte kullanacak geliştiricileri ifade eder)

Önemli olan, geliştiricilerin Kod İnceleme sırasında kodun normal şekilde çalıştığından emin olmak için kodu tam olarak test edebileceklerini umuyoruz. Ancak her durumda, bir gözden geçiren olarak bazı eşzamanlılık sorunları gibi bazı özel durumları da göz önünde bulundurmalısınız. Kullanıcının bakış açısından baktığınız kodda hata olmadığından emin olun.

Değişikliği doğrulayabilirsiniz, özellikle kullanıcının yüz yüze olduğu bir etki olduğunda, gözden geçiren kişi tüm değişikliği dikkatlice kontrol etmelidir. Bazen sadece koda bakarak bu değişikliğin kullanıcıları nasıl etkilediğini anlamak zordur Bu durumda, CL'de yama yapmak ve bunu kendiniz denemek için sakıncalıysanız, geliştiriciden size işlevsel bir demo sunmasını isteyebilirsiniz.

Diğerinin Kod İncelemesinde özel olması gerekir Dikkat Önemli olan CL'de eşzamanlı programlama olup olmadığıdır. Eşzamanlılık teorik olarak kilitlenmeye veya kaynak çekişmesine neden olabilir. Bu tür bir sorunu kod çalışırken tespit etmek zordur, bu nedenle birisinin (geliştiriciler ve incelemeciler) bütünü dikkatlice düşünmesi gerekir. İş parçacığı güvenliği sorunlarının ortaya çıkmamasını sağlamak için mantık. (Bu nedenle, kilitlenmelere ve kaynak çekişmesine ek olarak, Kod İncelemesinin karmaşıklığını artırmak da çok iş parçacıklı modeli kullanmayı reddetmek için bir neden olabilir.)

Karmaşıklık

Değişiklik beklenenden daha karmaşık mı? Her bir değişim düzeyini tespit etmek çok mu karmaşık? İşlev çok mu karmaşık? Sınıf çok mu karmaşık? "Karmaşık", kod okuyucularının kodu hızlı bir şekilde anlamasının zor olduğu anlamına gelir ve ayrıca geliştiriciler bu kodu çağırmaya veya değiştirmeye çalıştıklarında hataların ortaya çıkabileceği anlamına da gelebilir.

Tipik bir karmaşıklık sorunu, aşırı tasarımdır. Geliştiriciler kodu daha genel hale getirdiklerinde veya şu anda ihtiyaç duyulmayan birçok özellik eklediklerinde, gözden geçirenler bunların fazla tasarlanıp tasarlanmadığına daha fazla dikkat etmelidir. Gelecekte karşılaşılabilecek sorunlar hakkında spekülasyon yapmak yerine, geliştiricileri şu anda karşılaşılan sorunları çözmeye teşvik edin. Gelecekteki problemler karşılaşıldığında çözülmelidir, ancak o zaman sorunun doğasını ve gerçek ihtiyaçları görebilirsiniz.

Ölçek

Geliştiriciler birim testi, entegrasyon testi veya uçtan uca test yapmalıdır. Genel olarak, değişiklik sadece acil durumlar için değilse, testler değişikliğe dahil edilmelidir.

Değişiklikteki testlerin doğru, makul ve yararlı olmasını sağlayın. Testin kendisi kendini test edemediğinden ve test için nadiren test yazdığımızdan, testin etkili olduğundan emin olmalıyız.

Kodda bir şeyler ters giderse, test başarısız olur mu? Kod değişirse, yanlış mı bildirirler? Her testin iddiaları var mı? Testler farklı test yöntemlerine göre sınıflandırılıyor mu?

Unutmayın, testin ikilinin bir parçası olmadığını düşünmeyin Dikkat Karmaşıklığı.

isim

Geliştirici iyi bir adlandırma yöntemi kullanıyor mu? İyi bir adlandırma, bir öğenin (değişken, sınıf adı, vb.) Ne olduğunu veya ne için kullanıldığını tam olarak ifade edebilmeli, ancak okumayı zorlaştırmamalıdır.

Yorum Yap

Geliştirici net ve anlaşılır yorumlar yazdı mı? Tüm yorumlar gerekli mi? Yorumlar genellikle neyin yapıldığını değil nedenini açıklamalıdır. Kod kendinizi net bir şekilde açıklamak için net değilse, o zaman kod daha basit yazılabilir. Elbette bazı istisnalar var (normal ifadeler ve karmaşık algoritmalar gibi, yaptıklarını açıklayabilirseniz, kesinlikle kodu okuyanlara fayda sağlayacaktır), ancak çoğu yorum, kod gibi kodda yer almayan bilgilere atıfta bulunmalıdır. Arkasındaki karar.

Kaldırılabilecek bir yapılacaklar öğesinin listelenmesi veya kod değişiklikleri yapılmaması önerisi gibi değişikliğe ekli diğer notlar da önemlidir.

Yorumların sınıf, modül veya işlev belgelerinden farklı olduğuna dikkat edin Dokümantasyon, kod parçasının nasıl kullanıldığını ve kullanıldığında kodun davranışını açıklamak içindir.

stil

Google'da, ana akım diller ve hatta ana akım olmayan bazı dillerde, değişikliklerin bu stil yönergelerine uymasını sağlamak için kodlama stili yönergeleri vardır.

Stil kılavuzunda belirtilmeyen bir stilde iyileştirmeler yapmak istiyorsanız, geliştiricinin buranın geliştirilebileceğini düşündüğünüz bir yer olduğunu ancak zorunlu olmadığını bildirmek için yorumun önüne "Nit:" ekleyebilirsiniz. Ancak lütfen kişisel tercihinize göre değişikliklerin gönderilmesini engellemeyin.

Geliştiriciler, stil değişikliklerini diğer değişikliklerle bir araya getirmemelidir. Bu, değişikliklerde hangi değişikliklerin olduğunu görmeyi zorlaştırır, birleştirmeleri ve geri almaları daha karmaşık hale getirir ve ayrıca daha fazla soruna neden olur. Geliştiriciler tüm dosyayı yeniden biçimlendirmek isterlerse, yeniden biçimlendirilen dosyayı ayrı bir değişiklik ve işlev değişikliğini başka bir değişiklik olarak ele almalarına izin verin.

Dokümantasyon

Değişiklik, kullanıcının yapımı, testi, etkileşimi veya kodun yayınlanmasıyla ilgili mantığı değiştirirse, README'ler, g3doc sayfaları ve ilgili belgeler dahil olmak üzere ilgili belgelerin de güncellenip güncellenmediğini kontrol edin. Geliştiriciler bazı kodları siler veya terk ederse, ilgili belgeleri de silmeleri gerekip gerekmediğini düşünün. Belge doğruysa, geliştiricinin eklemesine izin verin.

Kod ayrıntıları

Tarayabileceğiniz veri dosyaları, oluşturulan kodlar veya büyük veri yapıları gibi Kod İncelemenizin tamamındaki her kod satırını kontrol edin, ancak yalnızca el yazısı sınıfları, işlevleri veya kod bloklarını taramayın ve ardından hepsinin normal şekilde çalıştığını varsaymayın. Açıkçası, bazı kodların dikkatlice kontrol edilmesi gerekir, bu tamamen size bağlıdır, ancak en azından tüm kodun ne yaptığını anlamalısınız.

Kodu anlamanız zorsa ve kod incelemesinin yavaşlamasına neden oluyorsa, incelemeden önce geliştiriciye nedenini bildirmeniz ve açıklamanız gerekir. Google'da en iyi mühendislere sahibiz ve siz de onlardan birisiniz. Siz okuyamıyorsanız, muhtemelen başkaları okuyamaz. Bu nedenle, geliştiricilerden kod mantığını netleştirmelerini istemek, gelecekteki geliştiricilere de yardımcı oluyor.

Kodu anlıyorsanız, ancak kod incelemeleri yapmaya yetkili olmadığınızı düşünüyorsanız, nitelikli değişiklik gözden geçirenlerinin kod incelemesi sırasında güvenlik, eşzamanlılık, erişilebilirlik, uluslararasılaştırma ve diğer konuları dikkate aldığından emin olun.

Bağlam

Değişiklik bağlam koduna bakmak, Kod Gözden Geçirme için çok yararlıdır, çünkü genellikle Kod Gözden Geçirme aracı, değiştirilen parçanın üstünde ve altında yalnızca birkaç satır kod görüntüler, ancak bazen değişikliğin normal şekilde çalışabilmesi için tüm dosyayı görüntülemeniz gerekir. Örneğin, 4 satır kodun eklendiğini görebilirsiniz, ancak tüm dosyayı gördüğünüzde, eklenen 4 satır kodun 50'den fazla satır içeren bir yöntemde olduğunu göreceksiniz.Bu yöntem artık birden fazla küçük yönteme bölünmelidir. Yukarı.

Kod Gözden Geçirme sırasında tüm sistemin bağlamını dikkate almak da önemlidir Bu değişiklik sistemin sağlığını iyileştirir mi? Veya sistem karmaşıklığını artırmak mı? Eksik test durumları mı var? ... Sistemin sağlığına zarar verecek kodları girmeyin. Küçük değişikliklerin yavaş yavaş birikmesi nedeniyle birçok sistem karmaşık hale gelir, bu nedenle karmaşıklığı artıran herhangi bir değişiklik yapmayın.

Öne Çıkanlar

Değişikliklerde iyi şeyler görürseniz, geliştiricilere harika bir iş çıkardıklarını söyleyin, özellikle de yorumlarınızda belirtilen sorunları çözmek için çok karmaşık bir yol kullandıklarında. Çok fazla kod incelemesi Dikkat Hata yüzünden, ancak geliştiriciyi iyi bir taraf gösterdiği için de övmelisiniz. Başkalarına akıl hocalığı yaparken, bazen geliştiricilere doğru yolu söylemek, onlara yanlış yolu söylemekten daha değerlidir.

sonuç olarak

Kod İncelemesi yaparken aşağıdakilere dikkat etmeniz gerekir:

Kod iyi tasarlanmış.
Kod işlevi kullanıcılar için yararlıdır.
Herhangi bir UI değişikliği iyi düşünülmeli ve iyi görünmelidir.
İplik güvenliğini sağlayın.
Kod gereksiz karmaşıklık eklemiyor.
Geliştirici, gelecekte ihtiyaç duyulacak bir şeyi yazmadı, ancak şimdi buna ihtiyaç olup olmadığını bilmiyor.
Kod, uygun birim testine sahiptir.
Test mantığı iyi tasarlanmış.
Geliştirici net bir isim kullanıyor.
Yorumlar açık ve pratiktir ve genellikle ne yaptığınızı değil nedenini açıklar.
Kod iyi belgelenmiştir.
Kod stili normla uyumludur.

Görmeniz istenen her kod satırını gözden geçirdiğinizden emin olun, kodun kalitesini artırdığınızdan emin olun ve iyileştirme için geliştiriciyi övün.

Kod inceleme adımları

özet

Artık CL'den ne almak istediğinizi bildiğinize göre, birçok dosya arasında incelemeyi tamamlamanın yolu nedir?

Bu değişiklik etkili olur mu? Bu değişiklik açıkça tanımlanmış mı?

Önce CL'nin en önemli bölümünü okuyun Bir bütün olarak iyi tasarlanmış mı?

Kalan değişiklikleri uygun sırayla okuyun.

Adım 1: Bu değişikliğe bakın

CL açıklamasını okuyun ve CL'nin genel içeriğini anlayın. Bu değişiklikler mantıklı mı? Her şeyden önce, eğer bu değişiklik mevcut değilse, lütfen bu değişikliklerin neden mevcut olmaması gerektiğini hemen açıklayın. Bu değişiklik gönderimini bu nedenle reddettiğinizde, geliştiriciye ne yapması gerektiğini söylemeniz çok iyidir.

Örneğin, şöyle diyebilirsiniz: "Bunun için harika bir iş çıkardınız, teşekkür ederim! Ancak, aslında FooWidget sistemini silmek için çalışıyoruz ve siz burada değişiklikler yapıyorsunuz, bu yüzden şimdi herhangi bir yeni değişiklik yapmak istemiyoruz. Peki, yeni BarWidget sınıfımızı yeniden düzenleyebilir misiniz? "

Gözden geçirenlerin yalnızca mevcut CL'yi reddetmekle kalmadıklarını ve alternatif öneriler sunduklarını, aynı zamanda kibarca yaptıklarını unutmayın. Bu nezaket önemlidir çünkü geliştiriciler arasında bile birbirimize saygı duyduğumuzu göstermek istiyoruz, özellikle de aynı fikirde olmadığımızda.

Birden fazla CL alırsanız ve değişiklik yapmak istemiyorsanız, CL tamamlanmadan önce daha fazla iletişime izin vermek için ekibin geliştirme sürecini veya dışarıdan katkıda bulunanların yayınlanmış sürecini yeniden tasarlamayı düşünmelisiniz. İnsanlara çok fazla iş yapmadan önce "bunu yapmayın" demek en iyisidir, çünkü artık atılacak veya tamamen yeniden yazılacaktır.

Adım 2: CL'nin ana parçalarını kontrol edin

Bu CL'nin "ana" bölümüne ait dosyaları bulun. Genel olarak konuşursak, bir CL'nin en önemli kısmı, en mantıklı değişikliklerin olduğu dosyadır. Bu, ilgili CL'nin anlaşılmasına yardımcı olur ve genellikle kod incelemesini hızlandırır. CL çok büyükse ve hangi parçaların ana parçalar olduğunu belirleyemiyorsanız, geliştiriciden size ilk önce neye bakmanız gerektiğini söylemesini veya ondan CL'yi birden çok CL'ye bölmesini isteyin.

CL'nin bu bölümünün bazı önemli tasarım sorunları olduğunu fark ederseniz, CL'nin geri kalanını gözden geçirmek için zamanınız olmasa bile bu yorumları hemen yazmalısınız. Aslında, CL'nin geri kalanını kontrol etmek zaman kaybı olabilir, çünkü eğer tasarım problemi yeterince ciddiyse, o zaman kontrol edilen diğer birçok kod kaybolacak ve zaten olmayacak.

Bu önemli tasarım yorumlarını iki ana nedenden dolayı hemen yazmak önemlidir:

Geliştiriciler genellikle gözden geçirene bir CL gönderir ve ardından gözden geçirmeyi beklerken CL'ye dayalı olarak hemen yeni çalışmaya başlar. CL'de gözden geçirdiğiniz büyük tasarım sorunları varsa, onların da gelecekteki CL'lerini yeniden tasarlamaları gerekecektir. Çok fazla gereksiz iş yapmadan onları durdurabilirsin.
Önemli tasarım değişiklikleri küçük değişikliklerden daha uzun sürer. Geliştiricilerin neredeyse son tarihleri vardır; işlerini son teslim tarihinden önce tamamlamak ve kod tabanında yüksek kaliteli kodu korumak için, geliştiricilerin CL'nin tüm önemli yeniden işlemlerini mümkün olan en kısa sürede başlatması gerekir.

Adım 3: Sırayla CL'nin geri kalanını okuyun

Bir bütün olarak CL ile ilgili önemli bir tasarım sorunu olmadığını onayladıktan sonra, lütfen dosyalara göz atmak için mantıksal bir sıra bulmaya çalışın ve herhangi bir dosya incelemesini kaçırmadığınızdan emin olun. Genel olarak, ana dosyalara göz attıktan sonra, her dosyaya kod inceleme aracının size gösterdiği sırayla göz atmak en kolayıdır. Bazen ana kodu okumadan önce test kodunu okumak da yararlıdır, çünkü o zaman değişikliğin ne yapması gerektiğini bilebilirsiniz.

Kod inceleme hızı

Kod İnceleme neden hızlı olmalı?

Google'da, geliştiricilerin bireysel olarak kod yazma hızını değil, ekibin yeni ürünler geliştirme hızını sürekli olarak optimize ediyoruz. Kişisel gelişimin hızı önemlidir ancak bir bütün olarak takımın hızı kadar önemli değildir.

Kod İnceleme yavaşsa, aşağıdaki şeyler olabilir:

Tüm ekibin hızı düşecek Evet, diğer kişilerin Kod İncelemesine hızlı yanıt vermeden diğer görevleri tamamlayabilirsiniz. Ancak, tüm ekibin yeni özellikleri ve hata düzeltmeleri, hiç kimse kimlik bilgisi vermediği için günler, haftalar ve hatta aylarca gecikebilir.
Geliştiriciler, kod inceleme sürecini sürdürmelidir Gözden geçiren kişi Kod İncelemesine nadiren yanıt verir, ancak her seferinde CL'de çok sayıda değişiklik önerirse, bu durum geliştiriciyi etkileyebilir. Genellikle geliştiriciler, gözden geçirenlerin çok katı olduklarından şikayet edebilirler. İnceleyen kişi, geliştirici güncellendikten sonra hızlı bir şekilde yanıt verebilir ve önemli iyileştirme için önerilerde bulunursa (kodun çalışma durumunu önemli ölçüde iyileştirebilen CL), şikayet ortadan kalkar. Kod İncelemesindeki şikayetlerin çoğu, CR hızı arttıkça ortadan kalkacaktır.
Kod kalitesini etkileyebilir. CR yavaşsa, geliştiricilere kötü kod göndermeleri için baskı yapabilir. CR yavaştır ve kod temizlemeyi, yeniden düzenlemeyi ve mevcut CL'nin daha da geliştirilmesini de etkileyecektir.

Kod İncelemesi hangi hızda yapılmalıdır?

Yüksek konsantrasyon gerektiren işler yapmıyorsanız, Kod İncelemesi olabildiğince hızlı olmalıdır. Kod İnceleme talebine bir iş günü içinde yanıt verilmelidir. Bu yönergelere uyulması, tipik bir CL'nin bir günde birden fazla gözden geçirme sürecinden geçmesi gerektiği anlamına gelir (gerekirse).

Kesintiye karşı hız

Bireyin hızının takımın hızından daha iyi olduğu tek bir durum var. Kod yazmak gibi önemli görevlerle uğraşıyorsanız, Kod İncelemesi yapmak için lütfen işinizi yarıda kesmeyin.Araştırmacının konsantrasyon kesintiye uğradıktan sonra konsantrasyon durumuna geri dönmesi uzun zaman alacaktır. Bu nedenle, diğer geliştiricilerin kendi kodlama çalışmalarını beklemesini ve kesintiye uğratmasını önlemek için, kesinlikle kayba değmez.

Bu nedenle, Kod Gözden Geçirme'ye kod yazma, öğle yemeğinden sonra, toplantıdan sonra, kilerden dönme gibi iş kesme noktalarında yanıt vermeniz önerilir ...

Hızlı cevap

Kod İncelemesinin hızı hakkında konuştuğumuzda, bir yandan yanıt süresine atıfta bulunurken, diğer yandan tüm İncelemenin sunulmasından onaylanmasına kadar geçen süreyi ifade eder. Tüm süreç yeterince hızlı olmalı, ancak herkes için tüm süreci hızlı bir şekilde tamamlamaktan daha hızlı tepki vermek daha önemlidir.

Tüm Kod İnceleme sürecini tamamlamak bazen uzun zaman alsa bile, gözden geçirenin tüm süreç boyunca hızlı yanıtı olabilir Çok "Yavaş" Kod İncelemesi nedeniyle geliştiricilerin hayal kırıklığını azaltın.

Kendinizi Kod İncelemesine adayamayacak kadar meşgulseniz, geliştiriciye Gözden Geçirmeye ne zaman gideceğinizi bildirmeli veya diğer gözden geçirenlerin hızlı bir şekilde yanıt vermesini önermeli veya bazı ön öneriler sağlamalısınız. (Not: Bu, işinizi yarıda kesmenizi değil, iş arasında makul bir şekilde yanıt vermenizi önermek içindir)

Gözden geçirenlerin, kodun standardı karşıladığından emin olmak için Kod İncelemesi yapmak için zaman ayırmaları gerekir.Her durumda, her yanıt yeterince hızlı olmalıdır.

Farklı saat dilimlerinde Kod İncelemesi

Farklı saat dilimlerinde bir Kod İncelemesiyle karşılaştığınızda, yazar eve gitmeden önce yanıt vermeye çalışın. Eve gittilerse, her gün şirkete gelmeden önce Kod İncelemesini tamamlamaya çalışın.

LGTM ve notlar

CR'yi daha hızlı hale getirmek için, bazı yorumlar çözülmemiş olsa bile, bazı durumlarda CR'nin önceden iletilmesi gerekir, örneğin:

İnceleyen, geliştiricinin tüm incelemecilerin önerilerini doğru şekilde çözeceğine güvenir.
Değişikliklerin geri kalanı küçüktür ve geliştiricilerin bunları yapması gerekmez.

Aksi açıkça belirtilmedikçe, gözden geçirenler bu seçeneklerden hangilerini kullanmayı düşündüklerini belirtmelidir.

Geliştirici ve gözden geçiren farklı saat dilimlerinde olduğunda, hazır hazırlığı geçmeye odaklanmalıdırlar, aksi takdirde geliştiricinin bir gün beklemesi gerekecektir.

Büyük CL

Birisi size çok büyük bir Kod İncelemesi gönderirse ve onu okumak için vaktiniz olduğundan emin değilseniz, geliştiricinin CL'yi birkaç küçük parçaya ayırmasını ve Kod İncelemesini bir kerede yerine birden çok kez bölmesini önerirsiniz. Teslim et. Geliştirici bazı ekstra işler yapsa bile, bölünebilir ve bölme de gözden geçirenler için faydalıdır.

CL birden fazla küçük CL'ye bölünemiyorsa, tüm kodu hızlı ve eksiksiz bir şekilde gözden geçirmek için zamanınız olmaz, sadece genel tasarım için bazı önerilerde bulunun ve ardından iyileştirme için geliştiriciye geri gönderin. Bir gözden geçiren olarak hedeflerinizden biri, geliştiricinin ilerlemesini engellememek veya kod kalitesinden ödün vermeden onları olabildiğince ileriye taşımaktır.

Kod İncelemesini sürekli iyileştirin

Bu önerileri uygularsanız ve bu yönergeleri Kod İnceleme'de sıkı bir şekilde uygularsanız, tüm Kod İnceleme sürecinin daha hızlı ve daha hızlı olacağını göreceksiniz. Geliştiriciler, sağlıklı kodun gereksinimlerini anlayacak ve en baştan mükemmel kodu teslim edecek ve ardından Kod İnceleme süresi gittikçe azalacaktır. Gözden geçiren kişi nasıl hızlı bir şekilde yanıt vereceğini öğrenecek ve bu Kod İnceleme sürecine gereksiz gecikmeler eklemeyecektir.

Ancak hızı artırmak için Kod İnceleme standartlarından ve kod kalitesinden ödün vermeyin. Uzun vadede bu, hızı artırmayacaktır.

Acil durumlar

Tabii ki, Kod Gözden Geçirme sürecini hızlı bir şekilde tamamlaması gereken bazı acil CL'ler var Şu anda, kalite kontrolü biraz gevşetilebilir. Hangilerinin acil, hangilerinin acil olmadığını anlamak için acil durumlar hakkındaki makaleye başvurabilirsiniz.

Kod incelemeleri nasıl yazılır

özet

nezaket
Ne demek istediğini açıkla.
Geliştiricilerin tartmalarına ve karar vermelerine yardımcı olmak için yönü ve sorunları açıkça belirtin.
Geliştiricileri açıklamak yerine kodu yorumlayarak ve düzene sokarak kafa karışıklığınızı çözmeye teşvik edin

nezaket

Genel olarak konuşursak, incelemeleri kodlarken kibar ve saygılı olmak, geliştiricileri daha net hale getirebilir ve daha fazla yardım alabilir. Bu, kod yorumlarınızın yalnızca kod için olduğundan ve geliştiriciler için olmadığından emin olmak içindir. Bunu her zaman yapmak zorunda değilsiniz, ancak yorumlarınız geliştiricileri kızdırdığında veya itiraz ettiğinde bu gereklidir. gibi:

Kötü örnek: "Neden burada ileti dizileri kullanasınız ve bunu yapmanın herhangi bir faydası olur mu?"

İyi bir örnek: "Bu eşzamanlılık modülünün programa çok yardımcı olduğunu bulamadım ve aynı zamanda programı artırdı. Sıranın karmaşıklığı, bu nedenle bu kodun çok iş parçacıklı yerine tek iş parçacıklı kullanmak için en iyisi olduğunu düşünüyorum.

Sebebini açıkla

Yukarıdaki "iyi" örneklerden de görebileceğiniz gibi, bu, geliştiricilerin bu yorumları neden yazdığınızı anlamalarına yardımcı olur. Bu bilgileri yorumlarınıza eklemeniz gerekmez, ancak niyetlerinizi açıklamak veya kodun kalitesini artırmak için daha fazla öneri vermek iyi bir uygulamadır.

Rehberlik et

Genel olarak konuşursak, CL'nin onarılması, gözden geçirenin değil geliştiricinin sorumluluğundadır. Geliştiricilere ayrıntılı çözümler veya kod sağlamanıza gerek yok.

Ancak bu, gözden geçirenlerin yardımcı olmaması gerektiği anlamına gelmez. Sorunu belirtmekle doğrudan rehberlik sağlamak arasında bir denge bulmanız gerekir. Sorunları belirtmek ve geliştiricilerin karar vermesine yardımcı olmak, geliştiricilerin iş arkadaşlarından öğrenmesine ve kod incelemesini kolaylaştırmasına yardımcı olabilir. Bu aynı zamanda daha iyi çözümlere yol açabilir, çünkü geliştiriciler kodu gözden geçirenlerden daha iyi bilir.

Buna rağmen, bazen doğrudan rehberlik, öneri ve hatta kod vermek daha yararlıdır. Kod incelemesinin temel amacı, mümkün olan en iyi CL'yi elde etmektir. İkincisi, geliştiricilerin becerilerini geliştirmektir, böylece sonraki incelemelerin sayısını azaltabilirsiniz.

Açıklamayı kabul et

Geliştiricilerden anlamadığınız bir kod parçasını açıklamalarını istemek yerine, yapmanız gereken şey, kodu daha net hale getirmek için kodu yeniden yazmalarına izin vermektir. Bir kod parçası çok karmaşık olmadığında ara sıra bazı yorumlar eklemek iyi bir uygulamadır.

Açıklama yalnızca Kod Gözden Geçirme aracında yazılır ve bu, gelecekteki kod okuyucuları için uygun değildir. Yalnızca birkaç durum uygulanabilir, örneğin, incelemenizin gerekliliklerine aşina değilsiniz, ancak geliştirici çoğu insanın bunu bildiğini açıklıyor.

Kod İncelemesinde çürütmelerle ilgilenme

Bazen geliştiriciler sizi Kod İncelemesinde reddedebilir, size katılmayabilirler veya çok katı olduğunuzdan şikayet edebilirler.

Kim haklı?

Geliştiriciler önerilerinize katılmadıklarında, önce doğru olup olmadıklarını düşünmek için bir dakikanızı ayırın, ancak genel olarak konuşursak, koda onlardan daha aşina olursunuz, bu nedenle bazı yönleri daha derin bir şekilde anlayabilirsiniz. Argümanları mantıklı mı? Çürütmeleri kod sağlığı açısından mantıklı mı? Öyleyse, haklı olduklarını ve sorunun çözüldüğünü onlara bildirin.

Ancak, geliştiriciler her zaman haklı değildir, bu durumda gözden geçiren kişi önerilerinin neden doğru olduğunu daha fazla açıklamalıdır. İyi bir açıklama yalnızca geliştiricinin yanıtının anlaşılmasını yansıtmaz, aynı zamanda neden değiştirildiğini de açıklar.

Gözden geçirenler, önerilerinin kod kalitesini artırabileceğine inanıyorlarsa ve sonuçta ortaya çıkan kod kalitesi iyileştirmelerinin, geliştiricilerin yaptığı ek çalışmaya değer olduğuna inanıyorlarsa, gözden geçirenler kendi konumlarına bağlı kalmalıdır.

Basamakları biriktirmezseniz bin millere ulaşamazsınız, küçük dereler biriktirmezseniz nehir yapamazsınız.

Bazen geliştiricinin kabul etmesini sağlamak için, defalarca açıklama yapmak için çok zaman harcamanız gerekir, ancak her zaman kibar olduğunuzdan emin olun ve aynı fikirde olmasanız bile geliştiriciye neyin peşinde olduğunu bildirin.

Geliştiricileri rahatsız et

Bazen gözden geçirenler, geliştiricinin değişiklik yapmasına izin verme konusunda ısrar etmenin geliştiriciyi rahatsız edebileceğini düşünür. Bazen geliştiriciler rahatsız olur, ancak bu durum genellikle kısa sürer ve daha sonra kod kalitelerini iyileştirme konusundaki yardımınızı takdir edeceklerdir. Kod İncelemesinde kibarsan, geliştiriciler hiç rahatsız olmayacak, bu tür endişeler gereksiz. Genelde geliştiricileri rahatsız eden kod kalitesi konusundaki ısrarınız değil, yorum yazma şeklinizdir.

Daha sonra düzelt

Çürütmenin yaygın bir nedeni, geliştiricilerin görevi mümkün olan en kısa sürede tamamlamak istemesidir. Her turda Kod Gözden Geçirme yapmak istemiyorlar ve ardından takip eden CL'de bu konularla ilgileneceklerini ve sadece bunu geçmeniz gerektiğini söyleyecekler. Bazı geliştiriciler iyi bir iş çıkarır, bu sorunlarla başa çıkmak için hemen takip CL'si gönderirler. Bununla birlikte, deneyimler bize, orijinal CL ne kadar uzun süre geçilirse, onu tamir etme olasılığının o kadar düşük olduğunu söylüyor. Geliştiriciler mevcut CL geçtikten hemen sonra düzeltmedikçe, düzeltemeyecekler. Bunun nedeni geliştiricilerin sorumsuz olması değil, yapacak çok işleri olduğu ve iş baskısı nedeniyle onarım işi unutulacağı içindir. Bu nedenle, geliştiricilerin bu sorunlarla şimdi CL'de ilgilenmesi ve "daha sonra temizlemeye devam etmesi" nin istenmeyen bir yol olduğu konusunda ısrar etmek en iyisidir.

CL'de yeni bir karmaşıklık ortaya çıkarsa, acil bir durum olmadığı sürece, teslim edilmeden önce temizlenmesi gerekir. CL'de bulunamayan bazı sorunlar ortaya çıkarsa, geliştiriciler bu hataları kaydetmeli ve bu sorunların unutulmaması için bunları kendilerine atamalıdır. Ayrıca kaydedilmiş hatalara işaret etmek için koda TODO yorumları ekleyebilirler.

Çok katı olmaktan şikayet edin

Daha önce Kod İncelemesine toleranslıysanız ve sonra aniden katı hale gelirseniz, bazı geliştiricilerin şikayet etmesine neden olabilir. Ancak önemli değil, Kod İncelemesini hızlandırmak genellikle bu şikayetleri ortadan kaldırır.

Bazen bu şikayetlerin ortadan kaldırılması birkaç ay sürebilir, ancak sonunda geliştiriciler, üretilen kaliteli kodu gördüklerinde katı Kod İncelemesinin değerini anlayacaklardır. Bazen, katı Kural İncelemesinin değerini gerçekten görmelerini sağlayacak bir şey olduğunda, en yüksek sesle protesto eden kişi en güçlü destekçiniz bile olur.

Çatışma çözümü

Yukarıdaki yöntemleri uygularsanız, ancak yine de Kod İncelemesinde çözülmemiş çatışmalarla karşılaşırsanız, çatışmaları çözmeye yardımcı olan yönergeler ve ilkeler hakkında bilgi edinmek için lütfen Kod İnceleme standartlarına tekrar başvurun.

Geliştirici Kılavuzu

İyi bir CL açıklaması yazın

Bir CL açıklaması, hangi değişikliklerin neden yapıldığına ilişkin genel bir kayıttır.

Sürüm kontrol geçmişimizin kalıcı bir parçası olacak ve yıllar içinde incelemecilerinize ek olarak yüzlerce kişi de okuyabilir.

Gelecek geliştiriciler, açıklamasına dayalı olacak aramak CL'niz.

Gelecekte, hazır detaylar olmadığı için birisi, belirsiz hafızasına dayanarak değişikliklerinizi arayabilir.

Tüm önemli ayrıntılar açıklama yerine kodda bulunuyorsa, CL'nizi bulmaları zor olacaktır.

ilk sıra

Kısa ve öz
Anlamsal bütünlük
Boş satır ayırma

CL açıklamasının ilk satırı, CL'nin yaptığı belirli işin kısa bir özeti ve ardından boş bir satır olmalıdır. Gelecekte, kodun çoğu budur aramak Okuyucular, bir kod parçasının sürüm kontrol geçmişine göz atarken bunu göreceklerdir, bu nedenle ilk satır, CL'nizin CL'nizi veya tüm açıklamasını okumadan, CL'nizin gerçekte ne yaptığı hakkında kabaca bir fikir edinebilecekleri kadar bilgilendirici olmalıdır.

Geleneğe göre, CL açıklamasının ilk satırı, bir komut (zorunlu bir cümle) gibi tam bir cümledir. Örneğin, "FizzBuzz RPC'yi silip yeni sistemle değiştirmek" yerine "FizzBuzz RPC'yi sil ve onu yeni sistemle değiştir" deyin.

Bununla birlikte, açıklamanın geri kalanını emir cümleleri olarak yazmanıza gerek yoktur.

Zengin vücut içeriği

Açıklamanın geri kalanı içerik açısından zengin olmalıdır. Çözülen sorunun kısa bir açıklamasını ve bunun neden en iyi yaklaşım olduğunu içerebilir. Bu yöntemin herhangi bir dezavantajı varsa belirtilmelidir. İlgili arka plan bilgilerini (hataların sayısı, karşılaştırma sonuçları gibi) ve tasarım belgelerine bağlantılar koyun. Küçük bir CL bile buna değer Dikkat detay. Lütfen gelecekte CL'ye koyun.

Karşı örnek

"Düzeltme hatası" yetersiz bir CL açıklamasıdır. Hata nedir? Nasıl düzelttin

Diğer bazı benzer kötü CL açıklamaları:

"Yapıyı düzelt."
"A gg yama."
"Kodu A'dan B'ye taşıma"
"Faz 1."
"A gg kolaylık fonksiyonları. "
"Tuhaf URL'leri öldürün."

İşte bazı gerçek CL açıklamaları. Yazarları, sağladıkları bilgilerin yararlı olduğunu düşünebilirler, ancak bir CL tanımlama niyeti vermemişlerdir.

İyi CL açıklaması

İşte iyi CL açıklamalarının bazı örnekleri.

İşlev değişikliği

rpc: RPC sunucusu mesaj serbest listesindeki boyut sınırını kaldırın.

FizzBuzz gibi sunucular çok büyük mesajlara sahiptir ve yeniden kullanımdan fayda sağlar.

Serbest listeyi büyütün ve gg Serbest liste girişlerini zaman içinde yavaşça serbest bırakan ve böylece boşta kalan sunucuların sonunda tüm serbest liste girişlerini serbest bırakan bir program.

İlk birkaç kelime CL'nin gerçekte yapmaktan bahsettiği şeyi tanımlar. Açıklamanın geri kalanı çözülecek sorunu, bunun neden iyi bir çözüm olduğunu ve özel uygulama ayrıntılarını açıklar.

Yeniden düzenleme

TimeStr ve Now yöntemlerini kullanmak için TimeKeeper ile bir Görev oluşturun.

Bir gg a Now yöntemi Görev için, böylece borglet alıcı yöntemi kaldırılabilir (bu yalnızca OOMCandidate tarafından borglet'in Şimdi yöntemini çağırmak için kullanılırdı). Bu, bir TimeKeeper'a yetki veren Borglet'teki yöntemlerin yerini alır.

Görevlerin Şimdi tedarik etmesine izin vermek, Borglet'e olan bağımlılığı ortadan kaldırmaya yönelik bir adımdır. Sonunda, Görevden Now'ı almaya bağlı olan ortak çalışanlar, doğrudan bir TimeKeeper kullanacak şekilde değiştirilmelidir, ancak bu, küçük adımlarda yeniden düzenleme için bir uyum sağladı.

Borglet Hiyerarşisini yeniden düzenleme uzun vadeli hedefini sürdürmek.

İlk satır, CL'nin ne yaptığını ve geçmişten nasıl değiştiğini açıklar.

Açıklamanın geri kalanı, spesifik uygulamayı, CL'nin giriş ve çıkışlarını, tatmin edici olmayan çözümleri ve gelecekteki olası talimatları tartışacaktır. Ayrıca bu değişikliğin neden gerekli olduğunu da açıklar.

Bağlama ihtiyaç duyan küçük CL

Status.py için bir Python3 oluşturma kuralı oluşturun.

Bu, bunu Python3'te olduğu gibi zaten kullanan tüketicilerin, kendi ağaçlarında bir yer yerine orijinal durum oluşturma kuralının yanındaki bir kurala bağlı olmalarına olanak tanır.Yeni tüketicileri, yapabiliyorlarsa Python2 yerine Python3'ü kullanmaya teşvik eder ve önemli ölçüde şu anda üzerinde çalışılan bazı otomatik derleme dosyası yeniden düzenleme araçlarını basitleştirir.

İlk cümle gerçekte ne yapıldığını açıklıyor. Açıklamanın geri kalanı, değişikliğin neden yapıldığını açıklar ve incelemeyi yapan kişiye birçok arka plan sağlar.

Lütfen CL'yi göndermeden önce açıklamayı kontrol edin

CL, gözden geçirme süresi boyunca büyük değişikliklere uğrayabilir. CL'yi göndermeden önce, CL'nin yaptığı şeyi açıklamanın hala yansıttığından emin olmak için CL tanımını gözden geçirmek gerekir.

Kısaltılmış CL

Neden bir dizi kısa CL yazasınız?

CL: