“Ben”, “Biz” veya Hiçbiri kod belgelerinde

Kendimi (C ++) kodunun kodunda (C ++) yararlı yorumlar yazarken buluyorum:

The reason we are doing this is...

“Ben” yerine “biz” kullanmamın nedeni, “biz” in sıklıkla tercih edildiği birçok akademik yazı yazmamdır.

İşte soru bu. Kodlamada birini diğerine tercih etmenin iyi bir nedeni var mı:

1. "Biz" i kullanın: Bunu yapmamızın nedeni ...
2. "Ben" i kullanın: Bunu yapmamın nedeni ...
3. İsmimi kullan: Bunun nedeni [my name]...
4. Pasif ses: Bunun yapılma nedeni ...
5. İkisi de: Bunu yapın çünkü ...

# 1'i seçiyorum çünkü bu şekilde yazmaya alışkınım ama belgeler yazar için değil, okuyucu için de geçerli, bu yüzden geliştirici adını eklemenin yardımcı olup olmadığını veya bunun için gereken başka bir şeyi ekleyip eklemediğini merak ediyorum. kodu korurken değiştirilebilecek.

Ben giderdim:

6.. Declarative: ...

"Bunun yapılmasının sebebi, her Foo'nun bir Bar'a sahip olması gerektiğidir" demekten ziyade, "Her Foo'nun bir Bar'a sahip olması" demeniz yeterli. Yorumunuzu, pasif olmaktan ziyade, sebebin aktif bir ifadesi haline getirin. Genel olarak daha iyi bir yazı stilidir, kodun niteliğine daha iyi uyar (bir şey yapar ) ve the reason this was donecümle hiçbir bilgi içermez. Ayrıca karşılaştığınız sorunu da tamamen ortadan kaldırır.

İkisini de tercih etmem ve aslında bu tanıtım cümlesini tamamen bırakıp, sadece o noktaya gelmek. Ayrıca sadece "bu" demekten kaçınmaya çalışıyorum çünkü yorumun kodla senkronize olup olmadığını söylemenin bir yolu yok. Başka bir deyişle, yerine:

// The reason this was done is to prevent null pointer exceptions later on.

Şöyle söylerdim:

// Frobnicate the widget first so foo can never be null.

Bir yorum eklediğiniz gerçeği, bir neden olduğunu belirttiğiniz anlamına gelir, bu nedenle gereksiz yere nedenini açıkladığınızı söylemenize gerek yoktur. Sebebi mümkün olduğu kadar açık bir şekilde belirtin, böylece daha sonra bu kodun nasıl korunacağını açık bir şekilde bilirler.

C # 'da (ve diğer dillerde birçok dokümantasyon aracında) dokümantasyon ile satır içi yorum arasında bir fark vardır. Benim kişisel görüşüm, Bobson ve diğerlerinin bir sınıf veya üyenin belgelerinde önerdiği gibi her zaman resmi, beyan niteliğindeki tarzı yorumlar kullanmanız gerektiği , ancak kurallar dahilinde, daha az resmi olmanın yanlış olduğu hiçbir şey yok. Aslında, bazen gayrı resmi bir yorum, bir şeyin neden resmi İngilizce’de tam bir açıklamadan daha iyi olmadığını açıklamakta daha etkilidir.

İşte noktayı gösteren bir örnek.

/// <summary>
/// Takes data from the remote client and stores it in the database.
/// </summary>
/// <param name="data">The data to store.</param>
public void StoreData(ComplexObject data)
{
    // Don't take candy from strangers
    ComplexObject safeData = SanitizeData(data);
    ...
}

Dikkate alınması gereken başka bir fikir, kodun neden açıklayıcı bir yorum yazmak yerine neden çalıştığını gösteren iyi hazırlanmış bir birim testi olacaktır. Bunun yorum yazmanın bir kaç faydası var:

1. Yorumlar, kod değiştiğinde her zaman değişmez; bu, daha sonra karışıklığa neden olabilir.

2. Birim testleri, bakıcıya kodla oynamak için kolay bir yol sağlar. Hangi değişiklikleri gözlemlemek için kırabileceğiniz ayrı birimleriniz varsa, yeni bir kod temeli öğrenmek çok daha kolay olabilir.

Bu cadde daha fazla çalışma gerektirse de, birim testi mükemmel bir dokümantasyon biçimi olabilir.

İyi yorumlar yazmak zordur ve en iyi yorumları bile okumak ve anlamak genellikle zordur. Eğer yorumunuz benim için özümseyecek kadar netse ve kod hakkında bilmem gerekenleri iletecek kadar kesinse, kullandığınız zamirleri hiç farketmez.

Birinin kodunu yorumlamasını istemekten nefret ediyorum, çünkü onların davası, zaman ve şahısların zamirleriyle ilgileniyorlar.

“Ben” yerine “biz” kullanmamın nedeni, “biz” in sıklıkla tercih edildiği birçok akademik yazı yazmamdır.

Bu kesin noktaya kimin karar verdiğini gizlemeye çalışmadığın sürece, akademik yazılar için bile kötü bir tarz.

Sorunuza gelince: Böyle bir yorum bırakmaz, başlamadığı sürece:

// TODO: clean this up, ...

veya çok önemli bir şeyi açıklamadığı sürece, koddan çok açık olmayabilir. Bu durumda, yorumu mümkün olduğunca kısa yapın.