Belgelerdeki belirli kod alanlarına nasıl başvurulur?

Bir projeden ayrılmak üzereyim ve gitmeden önce patronum benden belge kodu göndermemi istedi (çok iyi belgelemedim). Bu büyük bir mesele değil, proje çok karmaşık değil. Ama belgelerimde "XYZ hattında böyle ve böyle bir şey olduğuna dikkat edin" demek istediğim yerler buluyorum.

Bu durumda, tek bir kod satırının eklenmesi veya silinmesi dokümantasyonun hemen önüne geçeceğinden, belirli bir satır numarasına başvurmak mantıklı değildir. Satır numarasına bakmadan belirli bir kod satırına atıfta bulunmak için en iyi uygulama var mı?

Ben gibi yorumlarla kodu çöp düşündüm:

/* linetag 38FECD4F */

"38FECD4F", söz konusu satır için benzersiz bir etikettir. Sonra, '38FECD4F' etiketli hatta, böyle ve böyle bir şeyin gerçekleştiğine dikkat edin.

Başka fikir var mı? Kod birimlerini belirli bölümlerinden ziyade bir bütün olarak belgelemek genellikle daha iyi gibi hissediyorum, ancak bu özel proje söz konusu olduğunda, daha küçük birimlere hiçbir zaman yeniden yerleştirilmemiş UZUN prosedür kodları var.

Eğer doğru anlıyorsam, kendine özgü bir problemin var gibi görünüyor. Ne yapmak istediğiniz, aynı kodun başka bir bölümünde yazılmış yorumlarda belirli bir kod satırına atıfta bulunur.

Ben genellikle başka bir yerde yazılmış bazı yorum # exect satır başvurmak gerekir böyle senaryolar rastlamak değil - genellikle kodu doğru yerde yazılı belgelenir.

Bunu yapmanın standart bir yolunu bilmiyorum - ama başımın tepesinden ...

Kod kısımlarına bağlamı üzerinden, yani onları çevreleyen şeylerden bahsedebilirsiniz.

Func1 () tanımının üzerinde böyle ve benzeri şeylerin olduğuna dikkat edin

RecordXYZItr üzerinden yinelenen for döngüsünün hemen ardından, gc () yöntemini de çağırdığımızı unutmayın.

Dikkat: yahoo () yönteminde, değişken PQ bildiriminin hemen ardından, A ve B'deki değerleri de değiştiriyoruz, bu nedenle mapABC nesnesinin de kopyalanması gerekiyor

Başka bir yol da açıklayıcı etiketler eklemektir. Bunun gibi bir şey yerine, 38FECD4Fdiyebilir Some XYZ implementationya da BUGFIX 1474başka bir yere başvurabilirsiniz.

Kodun nasıl yazıldığına çok bağlıdır ve anladığım kadarıyla burada yapmak için olmadığınız bir sürü yeniden düzenleme yaratabileceğini anlıyorum.

Ancak ... belirli bir kod satırını bütün bir birim olarak belirtmeniz gerekiyorsa, bu, soyut bir işlemi temsil eden bazı kodların anlamına gelmez ve bu nedenle kendi yönteminde / işlevinde yeniden düzenlenebilir mi? Bir kez onun bir yöntem, oldukça kolay, sadece bakın namespace.class.methodTabii ki çok küçük, yaklaşık 5-10 satır uzunluğunda veya daha az yöntemlere sahip demek. Doxygen ile, belgeleri yöntemin üzerine koyabilirsiniz ve her zaman yöntemin / sınıfın / ad alanının adıyla senkronize kalır.

Bazı kod harici belgelerden koda bağlanmak dışında farklı bir yaklaşım kullanmanızı öneririm:

1. doxygen gibi bir araç kullanarak kodunuza yorumlar ekleyin .

2. bazı kavramları (yeni oluşturulan) kodun belgelerinde uygun olandan daha ayrıntılı olarak açıklamaya ihtiyaç duyulursa, her zaman ayrı bir belge oluşturabilir ve buna bağlantı verebilirsiniz.

Bu şekilde, belgeleri bir web sayfası veya PDF olarak kolayca oluşturabilirsiniz ve kodla tutarlı kalır. Bazı yapay etiketlerin kullanımı çok zor olacak ve girişimciler için anlaşılması daha da zorlaşacaktır.