İlk kişi yorumları rahatsız edici mi ve profesyonelce mi?

Sadece kendimi yazdığım bazı (arkaik Visual Basic 6.0) kodunda şu yorumu yazarken buldum:

If WindowState <> 1 Then
    'The form's not minimized, so we can resize it safely
    '...
End if

Bilinçli olarak neden “biz” i yorumlarımda kullandığımdan emin değilim. Şüpheliyim, çünkü kodun içinde birisinin, her bir satırdaki tüm komutları “yapıyor” sanki sadece onların gerçekleşmesini izlemek yerine sanıyorlar. Bu zihniyet ile, I can resize itşu anda "yapan" benim olduğumdan veya you can resize itgelecekte kim "yapıyor" ile konuştuğum gibi konuşuyormuş gibi kullanabilirdim, ancak bu davaların her ikisi de büyük olasılıkla olduğu gibi, "biz" i kullanırım sanki kodumla bir başkasını yönlendiririm.

Bunu basitçe yeniden yazabilirim it can be resizedve konuyu önleyebilirim, ama merakımı arttırdı: ilk kişiyi yorumlarda kullanmak yaygın mıdır, yoksa rahatsız edici ve / veya profesyonelce mi olduğu kabul edilir mi?

Yorumlar, insanların anlayabilmesi için yazılmalıdır. İnsanlar iletişim kurarken, genellikle "ben", "biz", "siz" vb.

Birileri bazı kodları anlamaya çalışırken, iki veya daha fazla oyuncu var: onu okuyan kişi ve kodun orijinal yazarı. "Biz" demek iyidir. 'Profesyonel' olmadıkça 'robot benzeri' demek istiyorsun.

Kodun sorumluluğunu otomatik olarak üstlendiğinden, 'I'yi kullanmaktan uzak durmanızı öneririm. Diğer insanlar okuyorsa, kötü görünecektir çünkü bu, bu durumda bir takım çalışması olması anlamına geliyor. 'Biz'i kullanma konusunda kayıtsızım. Bununla birlikte, diğer okuyucuları ung akılsızca dahil etmek gibi görünebilir.

Benim oyum hala netlik ve özlülük için geçerli Mesaj daha az ayrıntılı bir şekilde iletilebiliyorsa, neden başka bir şey seçsin? Yani, bu örnek ile ilgili olarak şunu yazarım:

'The form is not minimized so it can be resized safely.

İki yaklaşımdan birini alıyorum, genelde her ne daha iyi geliyorsa.

Gereksinimler veya gerekçeler gibi şeyleri açıklarken, sizin de olduğu gibi "biz" ile giderim:

// We can't proceed unless the user has given us this information.

Süreci açıklıyorsam, zorunlu (komut) bir ses kullanma eğilimindeyim (yanlış terim varsa düzeltin):

// Get the foo from bar and make sure it follows our required format.

İkincisi, kodu tekrarlamaya tehlikeli bir şekilde yaklaşabilir, ancak kullanımları vardır. Yani ben ya da biz kullanmıyoruz, bunun yerine aslında "sen" anlamına geliyor.

Bunun sadece kişisel olmayan akademik / teknik yazı stilinde bir değişiklik olduğunu düşünüyorum. Pasif sesi kullanarak, "kraliyet biz" i kullanarak ("bir" çok eskidir).

Genel bir kural olarak, bir yine de kullanacak spesifik olmayan - sürdürücüler fayda için yorum değil normalde sadece orijinal yazar vardır.

Niçin - Ben yorumlarda oldukça sık ilk kişi kullanabilir dedi ben özellikle kararlar ve ne ben düşünüyordum.

Yorumlar size bir şeyin neden yapıldığını söylemelidir, ne yapıldığını değil. Yapılmakta olan koddan belli değilse, kodu düzeltin, sadece yorum eklemeyin. Birinci kişi, ikinci kişi vb. Önemli değil, önemli olan gerekli bilgileri iletmek.

Kodu anlatmanız gerekiyorsa, örneğin

'ensure that the window is not minimized
If WindowState <> 1 Then
    'resize the window
    '...
End if

(Lütfen koddaki "1" gibi çıplak sabitleri kullanmayın)

Belki biz sihir yapma programı içindeki küçük çocuklar bahsetmektedir? :)

İngilizce pasif ses kullanmak zor ve kötü geliyor. İnsanlar kişi formlarını kullanmayı sever (ben, sen, biz, bir).

Örnek:

(Siz / biz / bir gerekir) üst pencereye yeniden boyutlandırma olayları geçirmek için bir temsilci kullanın

Pencereyi yeniden boyutlandırma olaylarını üst öğeye geçirmek için bir temsilci kullanılmalıdır.

Başka bir örnek (yorumlarda kişi formlarını sıkça ihmal edebileceğinizi unutmayın):

(Biz) bir istisna yakaladık. Bir hata iletişim kutusu göstererek (olacağız).

Bir istisna yakalandı ve bir hata iletişim kutusu gösterilecek.

PS. Edilgen olanı "siz" ile değiştirmek, ingilizce dilinde diğer dillere de sızmaya başladığı için çok yaygındır. Örneğin, ikinci tekil formun bulunduğu Fince (İngilizce "sen" gibi) oldukça komik geliyor.

Programın yürütülmesinden bahsediyorsanız, 'biz', 'siz' veya 'ben' değil. Antropomorfizm farkedilmeyecek kadar yaygın olabilir, ancak tehlikeli bir alışkanlıktır (PDF Warning. Dijkstra Warning.):

Antropomorfizmin hepsinden daha kötü olduğunu düşünüyorum. Şimdi “bir şeyler yapmaya çalışmak”, “bir şeyler yapmak istemek”, “doğru şeylere inanmak”, “bir şeyler bilmek” gibi programlar gördüm. Dilin bu kullanımının zararsız olduğuna inanmak kadar naif olmayın. Programcıyı, programın yürütülmesi ile kendini tanımlamaya davet eder ve neredeyse ona operasyonel semantik kullanımını zorlar.

İlk kişinin ya da "kraliyet biz" in profesyonelce ya da rahatsız edici göründüğünü sanmıyorum. "Olmak" fiiline sahip olmayan İngilizce altkümesi E-Prime'da İngilizce dilde yorum yazmak için çaba sarf etmemiz gerektiğini düşünüyorum .

Eğer yorumlarda "olmak" için aşırı kullanırsanız, aşağıdaki gibi kafa karıştırıcı ifadeler alırsınız:

// X is 10
// X is the user data of the newly-authenticated user
// X is a BigInt

Şey, belki de bir kerede hepsi değil, ama eşitlik sorunu gerçekten belirsizdir.

E-Prime'daki yazma gereksinimlerinin, yazarın eylemle birlikte bir oyuncuya göstermesi gerektiği için bu gereksinimleri daha net hale getirmeye yardımcı olduğunu düşünüyorum.

Yorum yapmak için doğru tarz, kişisel olmayan üçüncü kişidir; " Form küçültülmedi, bu yüzden güvenle yeniden boyutlandırılabilir ".

• Ben safım.
• Sen bir ahmaksın
• Biz çok resmi (ve kraliyet).

Her cümle bu şekilde yeniden ifade edilebilir (yukarıya bakın) ve yazmanın tek profesyonel yolu budur.

Yoruma bağlıdır.

Tipik olarak, İnek Ağzının önerdiği şekilde yorumlar yazıyorum . Aynı zamanda her zaman dokümantasyon üreten yorumları (Doxygen, JavaDoc) bu şekilde yazıyorum.

Ancak, çoğu kişi kaynak dosyalarda kimin yazdığını / dokunduğunu belirlemek için sürüm kontrolünün kullanılmasını ihmal eder. "Ben" demenin uygun olduğu zamanlar vardır, özellikle de "Ben" i takip etmek oldukça kolaylaştığında kodu yazan kişiye. Bir birey olarak bir karar vermişseniz, kodla uyumlu kararları belirlemek ve izlemek için "I" (sürüm kontrolü ile birlikte) kullanmanızı öneririm.

Benim iyi yaşlı babam (mhrip) şunu sorar: “Uğraşacak daha önemli şeyleriniz yok mu?”

Ancak, şahsen ben "biz" den hoşlanırım. Ayrıca, şirketimdeki tek çalışan olduğumu düşünerek neden kod yayınlamadığımızı, neden yayınlanmış belgelere yazdığımızı merak ediyorum.

Ancak ben kendim ve bu şekilde daha az yalnız hissettiğimize katılıyorum :)

"Biz" yazan ve "beni ve bilgisayarı" (veya "ekibim ve bilgisayarı") düşünen tek kişi ben miyim? "Biz" dışarının bize verdiği isteği yerine getirecek, bu da "bizim" isteğimizi okumamız, bazı pencereler açmamız, "iş" gereksinimlerimize dayanarak bazı hesaplamalar yapmamız gerektiği anlamına geliyor. Bu, aynı zamanda düşmanı değil, kodu kendi tarafınızın bir parçası olarak görmenize yardımcı olur.

Kısa yorumlar için, bazen ikinci kişiye, bir başkasına talimat veriyorum, neredeyse bir sonraki geliştiriciye yorumu okumaya yönlendiren bir mesaj olarak yazarım. Gibi

//You can get a session_id from SYSSession.getSessionID() if you need one

Daha uzun yorumlar (uzun işlevler üstbilgisi veya birkaç algoritma tanım satırı gibi) Nötr tutmaya çalışıyorum, birinci şahıs, ikinci şahıs veya üçüncü şahıs yok.

Kod yeterince açık olmadığı için bu yorumu eklediniz. Genelde iyi tanımlanmış yöntemlerle ifade etme niyetini yorumların kullanılmasından kaçınır buluyorum. Örneğin, bu satır, adlı bir yönteme taşınabildi CanThisFormBeResized.

İyi adlandırılmış bir yöntem, ancak küçük olmasına rağmen, bir yorumu yener, çünkü yorumların ve kodun senkronizasyondan çıkması kolaydır.

Dolayısıyla, çoğu yorum kodla ifade edilebiliyorsa, bu yorumların çok az nedenini bırakır

• Yorumunuz sizce ise, "Ben"
• Yorumunuzun paylaşılan bir fikir olması gerektiğini düşünüyorsanız (örneğin en iyi uygulama), "biz" ile başlayın.
• Yorumunuz yönelik ise bir yarım akıllı tarafından yazılmış bazı tehlikeli kod ve yorumunuza hurda ve yürümek ve onlara yumruk sonra onlarla bu yüzü yüze hitap bir meslektaşım kafa karıştırıcı kod.

Genel bir kural olarak, ilk kişiyi kullanmanızı öneririm, yani I.

Neden? Ben'in iyelik yapısından dolayı değil, insanlar başka bir bakış açısıyla konuştukları için, çok fazla kelime kullanma veya cümleleri çok karmaşık hale getirme ve şeyleri açıklamaya çalışırken kaybolma eğilimindedirler. İlk kişi her zaman okuması en kolay olma eğilimindedir.

Şahsen ben yazarım (C # ile):

if (WindowState != WindowState.Minimised)
{
     ResizeWindowSafely();
}

Veya bu satırlar boyunca bir şey, yorumlara gerek yok.