Belge stili: Bir açıklamada değişken adlarını metnin geri kalanından nasıl ayırırsınız?

Question

Bu oldukça gereksiz ve ilgisiz bir soru, korkarım, ama her zaman bunu merak ediyorum. Satır içi yorumlarla kod oluşturduğunuzda (oluşturulan belgelerde görünecek olan yorumların aksine) ve yorumda bir değişkenin adı göründüğünde, normal metinden nasıl ayırt edersiniz? Örnek: "Tür" değişkenin adıdır. Yorumun metninin sadece bir parçası değil, bir sembol olduğunu belirtmek için bunu herhangi bir şekilde işaretler misiniz? Böyle şeyler gördüm: Ayrıca

// Try to parse "type". 
// Try to parse 'type'. 
// Try to parse *type*. 
// Try to parse <type>. 
// Try to parse [type]. 

Ve:

// Try to parse variable type. 

(ı sonuncusu çok yararlı olduğunu düşünmüyorum; bu biraz kafa karıştırıcı, siz düşünebildiğim "değişken" dir bir sıfat var)

Herhangi bir tercihiniz var mı? Bir çeşit işaretleyici kullanmam gerektiğini buldum; aksi halde yorumlar bazen belirsizdir veya en azından yorumda belirli bir kelimeyi fark ettiğinizde bunları tekrar okumanıza zorlar.

(Tabii, jeneratör için uygun etiketleri kullanmak belgelerinde görünecektir yorumlarında: @code, <kod> </kod >, vs)

teşekkürler! Eğer sürece belgelere genelinde tutarlılık bulunmadığından, söz bu stilleri

Answer 1

HERHANGİ.

Answer 2

bu sorun var doent i PHP yapıyorum vaktimin,% 99.9: (ama bunu düşünmek tek tırnak işareti

// Try to parse $type. 

ama diğer dillerde bazı şeyler yaptığınızda, i gibi örnekte

// Try to parse 'type'. 

Answer 3

olduğu kod satırı ile kombine açıklamalarınızı:)); kullandığınız çok önemli değil, ama her yorumda değiştirmeyi değil, aynı her zaman kullanmalıdır yorumlanmak, yazılanları anlamak için gereken tüm bağlamı sağlar. Aslında bir kod bloğunu açıklamak amacıyla yapılan bir yorumla uğraşırken bile, genellikle bir sorun olmayacaktır - code + comment = context for understanding.

Hepsi de, ve bir başkasının bahsettiği gibi: tutarlı olduğunuz sürece, seçtiğiniz yöntemlerden herhangi biri çalışır.