Sürüm kontrolü yorumları için diğer kullanıcılar ne yapar / önerir - geçmiş veya şimdiki zaman?

yani

• Değiştirilen X-Y olması.
• veya
• X'in y olarak değiştirilmesi .

Yorumlar bağlam içinde okunmalıdır, bu yüzden:

Mevcut

Bir yöntemin yukarısındaki kaynak yorumlarında veya bir davranış oluşmadan önce:

// This function does X
function doX() { ... }

geçmiş

Bazı davranışlar meydana geldikten sonraki kaynak yorumlar için

function doX() {
    widget.doY()
    // did Y to widget to prepare it for Z
    ...
}

Ve taahhüt mesajları için

X fonksiyonu değişti

Karışık örnek:

// This function does X
function doX() {
    widget.doY()
    // did Y to widget to prepare it for Z
    ....
}

Geçmiş - Gelecekte okuyan herkes, değişimin geçmişte olduğu gibi hareket etmesini ifade edecektir.

Bir şeyi "Değiştirme" olarak ifade etmek, şu anda değişiklik yapma aşamasında olduğunuzu ve kodun tamamlanamayacağını gösterir.

not: Şahsen, sadece ciddi bir değişiklik olduğunda değişiklik yorumları koydum.

Yorumlar statik şeylerdir, bu yüzden programın durumunu olduğu gibi değil, olduğu gibi sunmalıdırlar . Özel sorunuza cevap vermek için geçmiş zamanı kullanmak daha uygun olacaktır .

Ancak, bu tür bir yorum sürüm kontrol sisteminize daha uygundur. Sürüm kontrolü, manuel izleme işlemlerinden daha iyi bir değişiklik izleme işi yapar. Versiyon kontrol sistemleri ile bu değişiklikler değişikliğin yapıldığı anda geçerli olduğu için şimdiki zamanda belgelenmesi daha uygundur . Ancak, her ikisi de işe yarayacaktır.

Çok kodunda sadece yorum kodu - amaç, iş mantığı ve istisnai durumlar - anlamak için gerekli olması gerektiğini tavsiye ediyoruz. Değişiklik seti belgelerini sürüm kontrol sisteminize bırakın. VCS kullanmıyorsanız, şimdi başlayın. Ücretsiz olan birkaç yüksek kaliteli VCS vardır (Subversion, Mercurial, Git, vb.).

Zorunlu şimdiki zamanı kullanıyorum, yani:

"X" i "y" olarak değiştirin

Bu, Git geliştiricileri tarafından önerilir :

• organ anlamlı bir taahhüt mesajı sağlamalıdır:
  • zorunlu, şimdiki zamanı kullanır: "değiştir", "değiştirilmedi" veya "değişiklikler" değil.

İlk başta biraz garip gelebilir, ancak bir taahhüdü bir şey yapan bir yama olarak düşünüyorsanız, daha mantıklı. (Bu özellikle Git gibi bir DVCS'de, repoda hareket eden diğer insanlardan değişiklik kümeleri çektiğinizde geçerlidir.)

Gerçekten önemli değil; Bence bu kişisel tarz ve tercih. Hemen hemen her şeyi yazarken, sadece kendinizle ve diğer yorumlarla tutarlı olun.

Kod yorumlarını okumak doğal olmalıdır.

Kendinize söyleyerek kodu okuyorsanız "Bu kod olan bu o zaman kod okuma birisi de düşünerek nasıl muhtemel olduğu gibi o zaman şimdiki zamanda yorumunu yazmalı X yapıyor". Diğer yandan belli bir noktada sen düşünme olsaydı "Bu kod did o zaman geçmiş zaman olmalıdır X". Sonuçta, herhangi bir nedenle kodunuzu nasıl yorumlayacağınıza dair yönergeler (yani bir takım projesi veya bir sınıf, vb.) Altında olmadığınız sürece kişisel tercihinize bağlıdır.

Git kullanıyorsanız, git araçlarıyla (örneğin birleştirme) oluşturulan kesin mesajlar şimdiki zamanı kullandığından, kural şimdiki zamanı kullanmaktır.

Geçmiş zamanı kullanmalısın.

Bu taahhüdün neyi başardığı sorusuna cevap vermenizin nedeni ? Bunu VCS'nize ne yaptığınızı söyleme olarak düşünün:

Taahhüt 123
XYZ'yi ABC yapacak şekilde değiştirdi

Karşı örnekler vermek için, gelecekteki zamanı kullanmak, başka birinden yapmasını istiyormuşsunuz gibi ses çıkarır:

Taahhüt 123
ABC yapmak için XYZ değiştirme

ve şimdiki gergin sesleri yarı yolda gibi kullanıyor:

Taahhüt 123
ABC yapmak için XYZ değiştirme

Şu anki zamanı kullanın: "X'i Y olarak değiştirin", neredeyse açık bir YAPILACAKLAR listesindeki bir öğeymiş gibi.

Genel olarak, tıpkı bir senaryo gibi, "olmak" ve "olduğu" gibi fiillerden kaçının. Örneğin, "yürüyor" değil, "yürüyor".

Ancak bu özel örnekte - kod yorumları hakkında konuşuyorsanız ve check-in yorumları hakkında konuşmuyorsanız - "X'i Y'ye Değiştir" in korkunç bir yorum olduğuna inanıyorum. Yeni bilgi eklemez ve kodun değiştirilmesi gerekiyorsa, bu yanlış bile olabilir. Kodu bir yönteme (veya sınıfa) ayıklamak ve bunun yerine bu yöntemi belgelemek daha iyidir. Yeterince açıksa, sadece iyi bir yöntem adı yeterli olacaktır.

Bundan bahsetmek gerekirse, belgeleme yöntemleri için gelecekteki zamanı kullanabilirsiniz, örneğin: "Sağlanan sayı negatifse, abssayının büyüklüğünü döndürür."

Yorumlar, yazılan herhangi bir şey gibi, bir şeyin ifadeleridir (ve olmalıdır) ve sadece doğal dillerde aynı kuralları izlemelidirler (belgelenen duruma veya esere özgü kısayolları ve kısaltmaları dikkate alarak).

Şimdiki zamana ilişkin yorumlar ( .ie "değişiyor" veya "değişiyor" ), dokümante edilmiş algoritma tarafından çalıştırılan bir veri parçasının bir şekilde etkilendiğini göstermektedir. Yani, kodun ne yaptığını veya işlenen verilere neler olduğunu gösterir.

Geçmiş zamandaki yorumlar, yorumun bulunduğu noktadan önce olan bir şeyin iddiasını, önkoşulunu veya son koşulunu göstermelidir. Örneğin:

Bu kod bloğunu girmeden önce giriş zaten doğrulandı

veya

Veriler bu kodun yürütülmesinin sonunda dosyaya yazılmıştır

Geçmiş zamandaki yorumlar, bir şeyin neden yapıldığını da açıklayabilir ( bu işlev, eski veritabanı ile ilgili bir sorunla başa çıkmak için X ve Y'yi yapar. )

Geçmiş zamanda kodun kendisinde (.ie. X, Y olarak değiştirildi ) bir değişiklik olduğunu gösteren yorumlar kodda bulunmamalıdır. Bunun yerine kaynak kodu deposunda revizyon yorumları olarak bulunmalıdırlar.

Gelecekteki yorumlar, yerine getirilmesi veya ele alınması gereken bir durumu göstermelidir, ancak X veya Y nedeni için şu anda yapılmamaktadır. Örneğin:

Sonunda db'yi taşıdığımızda, bu mantığı değiştirmemiz gerekecek

veya

YAPILACAKLAR: en kısa zamanda, giriş doğrulamasını tekrar ziyaret edin - X veya Y tipi giriş için başarısız olabilir, şu anda uygulanamayan büyük değişiklikler gerektirebilir.

Daha sonra yapılacak olan TODO yorum türleri için, bu tür değişikliklerin gerçekten gerçekleştiğinden emin olmak için başka bir belge biçimi mevcut olmalıdır. İstediğiniz son şey zaman ve mekanda kaybedilen TODO'lar: P

Bir tuz tanesi ile alın, ancak genellikle kendi yorumlarımı yaparken genellikle takip ettiğim kurallardır.

Yorumlarında tutarlılık çok önemlidir iken bu nedenle, çok önemli, insana iletişim hakkındadır değil ilkeler kendilerini iyi iletişimin şekilde olsun zaman olsun ilkelerine saplanıp için. Bununla birlikte, aşağıdaki sözde standartları kullanıyorum:

• İstenen bir davranışı açıklayan yorumlar şimdiki zaman zorunlu bir cümle biçimindedir.

  // Calculate the width of the curve at x height.
  

• Kodlamadaki genel temaları tanımlamak (ve aramayı kolaylaştırmak için) bir dizi tam kapsamlı anahtar kelime kullanın:

  // NOTE: <This code was written this way for a reason.>
  // TODO: <This code is incomplete. Finish it.>
  // HACK: <This code was written this way for a reason that you won't like.>
  // FIXME: <This code has a known flaw. Fix it.>