Kod yorumlarında Dönemler / Tam Duruma ilişkin düşünceleriniz nelerdir? [kapalı]

Bunu SO Tavern'de sordum , bu yüzden soruyu buraya gönderiyorum. Bunun ilginç bir soru olduğunu düşündüm. (Tabii ki SO'ya ait değil, ama bence burada sorun yok.)

Kod yorumlarınıza dönemler (veya OP'nin yazdığı gibi "tam duraklar") ekler misiniz?

İlgili tutmak için, neden ?

Tam duraklama cümleleri sona erdirmek içindir, ancak bir yorum kodla çevrili yalnızca bir cümle içeriyorsa, bence tam durma gerekli değildir. Bazen ilk harfi bile büyük harf yapmıyorum. Öte yandan, ayrıntılı bir çok satırlı yorum, tam noktalama işaretlerine ihtiyaç duyar.

// This function returns an average of two integers. Note that it may
// return an irrelevant result if the sum of a and b exceeds the int
// boundaries.

int avg(int a, int b)   // make it static maybe?
{
    // A better algorithm is needed that never overflows
    return (a + b) / 2; 
}

Evet, çünkü yorumlar İngilizce'dir ve uygun İngilizce, noktalama işaretleri kullanır.

Kod yorumlarınıza dönemler (veya OP'nin yazdığı gibi "tam duraklar") ekler misiniz?

İlgili tutmak için, neden?

Aynı sebepten dolayı "normal" metin yazarken bunları ekliyorum - bunlar yazılı dilin bir parçası ve onlar hakkında özel bir şey olmamalı. Paragrafların yanı sıra bir cümle (bir satır) yorum yazarken bunları eşit kullanırım.

Kaynak kod normal bir metin değil ve bu nedenle farklı kurallar kullanıyoruz. Basit ;-)

Yorum yazarsanız, onların İngilizce dilinde yazıldığını umarsınız. Bu durumda, kişi düzgün bir şekilde noktalamalı. Aksi takdirde tembel olurdu.

Tam bir cümle (veya daha fazla) yazarsam, evet. Yapmazsam, o zaman bazen hayır, ama genellikle hala evet.

Ayrıca bazen deliriyorum ve ünlem işareti, soru işareti vb. Kullanıyorum.)

Neden olarak, kısmen sadece özel olduğum için ve kısmen uygun noktalamaların çok netlik getirebileceğini düşündüğüm için.

Diğer cevaplar ve popülerlikleri, uzun duraklarda tam duraklamanın iyi anlaşıldığını ve muhtemelen tek gömleklerde önlenebileceğini açıkça ortaya koydu.

İlgili olabilecek bir diğer nokta, ünlem işareti, özellikle katları olmaktan kaçınmaktır . Örnek:

    // Though loop is labor-intensive, performance is fine with with 95K cases!!!

ve

    // This code really sucks!

Öte yandan, soru işaretleri bazen oldukça yararlıdır:

    // TODO: What does Crojpler.bway() actually do?

Değişir. Bir kod bloğunun ne yaptığını açıklayan büyük, uygun bir paragraf yazarsam, diğer uygun yazım parçaları gibi onu doğru şekilde işaretlerim. OTOH, sadece tek bir kod satırını yorumladığımda söylemiyorum.

Niye ya? - SMS mesajlarında kısayol cümleleri kullanabilirken, neden doğru yazıyı kullanarak e-posta yazdığımı benzer. Bir durumda, uygun bir metin bloğu yazmak için oturuyorum, bu yüzden sadece otomatik olarak "doğru şekilde yapıyorum", diğerinde bir noktaya değinmek için kısa bir not.

Kodumdan gerçek örnekler:

Kısa not yorumu:

// check for vk_enter

"Uygun" yöntem dokümantasyonu:

// This method sets up a workspace tab with the given name. Each MDI window has a parent
// workspace specified when it's saved. The code which loads each MDI window then point it to
// the correct workspace.

Evet, bu şekilde iyi bir kodlama kuralı oluşturduğunuzu ve aynı zamanda kodunuzu inceleyen 3. bir kişi için temiz bir okunaklı kod oluşturduğunu düşünüyorum.

Ben olacak her zaman düzgün yararlanmak ve noktalama oluştururken XML açıklamaları ben görülebilir beklediklerini IntelliSense'de ve bizim de üretilen belgeler . Bunlar çok daha resmi yapılar ve böyle ele alınmaları gerekiyor.

Bununla birlikte, bir kod bloğunun gövdesinde henüz görülen yorumlar, mümkün olduğu kadar açık olmalıdır. Bunu nasıl başardıkları programcıya kalmış.