Satır içi kod yorumları için en iyi yaklaşım nedir?

Biz 20 yaşında eski bir kod temeli bazı refactoring yapıyoruz, ve meslektaşım ile kod (plsql, java) yorum biçimi hakkında bir tartışma yaşıyorum.

Yorumlar için varsayılan bir biçim yoktur, ancak çoğu durumda insanlar yorumda böyle bir şey yapar:

// date (year, year-month, yyyy-mm-dd, dd/mm/yyyy), (author id, author name, author nickname) and comment

istediğim gelecekteki ve geçmiş yorumlar için önerilen biçimi:

// {yyyy-mm-dd}, unique_author_company_id, comment

Meslektaşım yalnızca yoruma ihtiyacımız olduğunu ve geçmiş ve gelecek tüm yorumları bu biçimde yeniden biçimlendirmemiz gerektiğini söylüyor:

// comment

Argümanlarım:

• Bakım nedenleriyle söylüyorum, ne zaman ve kimin bir değişiklik yaptığını bilmek önemlidir (bu bilgi bile SCM'de bulunur).
• Kod yaşıyor ve bu nedenle bir tarihi var.
• Çünkü değişiklik tarihleri ​​olmadan bir değişikliğin ne zaman SCM aracını açmadan tanıtıldığını bilmek ve uzun nesne geçmişinde arama yapmak imkansızdır.
• çünkü yazar çok önemli, yazar değişikliği yazarlık değişikliğinden daha güvenilir
• Çeviklik nedenleri, SCM aracını açmaya ve gezinmeye gerek yok
• insanlar birisinin 15 yıl önce yaptığı bir şeyi değiştirmekten, yakın zamanda yaratılan veya değiştirilen bir şeyden daha fazla korkarlardı.
• vb.

Meslektaşımın iddiaları:

• Tarih SCM'de
• Geliştiriciler doğrudan koddaki kodun geçmişinin farkında olmamalıdır
• Paketler 15k satır uzunluğunda ve yapılandırılmamış yorumlar bu paketlerin anlaşılmasını zorlaştırıyor

Sizce en iyi yaklaşım nedir? Yoksa bu sorunu çözmek için daha iyi bir yaklaşımınız mı var?

Genel yorumlar

Ben yorumlara büyük bir inanan (neden değil) içindir . Soruna nasıl düştüğünüz hakkında yorum eklemeye başladığınızda, yorumların kodla ilgili olarak sürdürülmesini zorunlu kılmadığı konusunda yorum yapmaya başladığınızda ( neden genellikle değişmeyecektir (açıklamanın zaman içinde neden geliştirilebileceği)).

Aynı şekilde date / authorInfo, kodun neden bu şekilde yapıldığı konusunda size hiçbir şey kazandırmaz; tıpkı zaman içinde nasıl dejenere olabileceği gibi, çünkü herhangi bir alet tarafından yaptırım yoktur. Ayrıca aynı bilgiler zaten kaynak kontrol sisteminde saklanır (böylece çabayı çoğaltırsınız (ancak daha az güvenilir bir şekilde)).

Argümanları incelemek:

Bakım nedenleriyle söylüyorum, ne zaman ve kimin bir değişiklik yaptığını bilmek önemlidir (bu bilgi bile SCM'de bulunur).

Neden. Bunların hiçbiri bana kodu korumak için önemli değil. Yazarla konuşmanız gerekiyorsa, bu bilgiyi kaynak kontrolünden bulmak nispeten basittir.

Kodun hayatının bir nedeni var.

Geçmiş, kaynak denetiminde saklanır.
Ayrıca yorumun o kişi tarafından yazıldığına inanıyor musunuz? Howyorumlar zamanla bozulma eğilimindedir, bu nedenle bu tür bir tarih güvenilmez hale gelir. Kaynak kontrol sistemleri ise çok doğru bir geçmişe sahip olacak ve yorumların ne zaman eklendiğini / kaldırıldığını doğru olarak görebilirsiniz.

Çünkü değişiklik tarihi olmadan SCM aracını açmadan bir değişikliğin ne zaman eklendiğini bilmek ve uzun nesne geçmişinde arama yapmak imkansızdır.

Yorumdaki verilere güveniyorsanız.
Bu tür şeylerle ilgili sorunlardan biri, yorumların kodla ilgili olarak yanlış hale gelmesidir. İş için doğru araca geri dönün. Kaynak kontrol sistemi bunu kullanıcının müdahalesine gerek kalmadan doğru şekilde yapacaktır. Kaynak kontrol sisteminiz bir acıysa, belki de daha uygun bir şekilde nasıl kullanacağınızı öğrenmeniz gerekir (bu işlevsellik genellikle kolaydır) veya desteklemiyorsa daha iyi bir kaynak kontrol sistemi bulun.

yazar çok önemli olduğu için, yazarın değişmesi yazarın değişmesinden daha güvenilirdir

Tüm yazarlar (kendinizden ayrı olarak) eşit derecede güvenilirdir.

Çeviklik nedenleri, SCM aracında gezinmeye gerek yok

Kaynak kontrol aracınız yanlış kullanıldığında bu kadar külfetli iseniz veya kaynak kontrol sistemine erişmek için yanlış araç setini kullanıyorsunuzdur.

insanlar birisinin 15 yıl önce yaptığı bir şeyi değiştirmekten korkuyorlardı.

Kod 15 yıl sürdüyse, incelemeye gerek kalmadan sadece 6 ay süren koddan daha sağlam olması daha olasıdır. Kararlı kod sabit kalma eğilimindedir, buggy kodu zamanla daha karmaşık hale gelme eğilimindedir (buggy olmasının nedeni sorun ilk düşünce kadar basit değildir).

Bilgi almak için kaynak kontrolünü kullanmak için daha fazla neden.

Tarih SCM'de

Evet. En iyi neden.

Geliştiriciler kodun doğrudan koddaki geçmişinin farkında olmamalıdır

Bu bilgiye gerçekten ihtiyacım olursa, kaynak kontrolünde arayacağım.
Aksi takdirde ilgili değildir.

Paketler 15k satır uzunluğunda ve yapılandırılmamış yorumlar alıyor, bu paketlerin anlaşılması daha zor

Yorumlar, neden bir şey yaptığınızı açıklamalıdır.
Yorumlar gerektiğini DEĞİL (algoritma açık değildir sürece) kodunun nasıl tarif ediyor.

Meslektaşını şiddetle destekliyorum. Eski kodu bir yorumda tutmadıkça neden bir şeyin değiştiğini anlamak istiyorsanız, SCM'ye bakmadan yine de alamazsınız.

Kod tonlarca yorum yazmadan anlaşılamayacak kadar karmaşıksa, kodu tonlarca yorum yapmadan okunabilir / bakım yapılabilir hale getirmek için enerjinizi yeniden düzenlemeye enerji yatırmanızı öneririm.

Sonuçta, programcıları işe alıyorsunuz, hikaye anlatıcıları değil ;-)