Neden ya da neyin yerine niçin size söyleyen yorum örnekleri nelerdir? [kapalı]


78

Öncelikle, bu soruda kaynak kod yorumlamanın iyi ya da kötü olup olmadığı konusunda polemikten uzak durmak istiyorum. Sadece insanların NEDEN, NE veya NASIL olduğunu söyleyen yorumlar hakkında konuştuklarında ne anlama geldiklerini daha net anlamaya çalışıyorum.

Sık sık "Yorumlar size NEDEN söylemelidir; kodun NASIL olduğunu söylemelidir" gibi yönergeler görüyoruz. Soyut bir seviyedeki ifadeyle aynı fikirde olmak kolaydır. Ancak, insanlar bunu genellikle bir dogma gibi bırakırlar ve daha fazla açıklama yapmadan odadan çıkarlar. Bunu birçok farklı yerde ve bağlamda kullandım, insanlar parantez üzerinde hemfikir olabilir gibi görünüyorlar, ama tamamen farklı şeyler hakkında konuşuyor gibi görünüyorlar.

Öyleyse, soruya geri dönelim: Yorumlar size NEDEN anlatmalıysa, neden NEDEN bahsettik? Bu ilk etapta bu kod parçasının bulunmasının nedeni bu mu? Bu parça kodunun yapması gereken bu mu? Birisinin net bir açıklama yapıp yapamayacağına gerçekten çok sevinirim ve sonra bazı iyi örnekler eklerim (kötü örneklere gerçekten ihtiyaç duyulmaz, ancak bunları kontrast eklemek için serbest bırakılır).

Yorumların iyi ya da kötü olup olmadığına dair birçok soru var, ancak size Niçin olduğunu söyleyen iyi yorum örnekleri hakkında kesin soruya değinen kimse yok


36
Bazen en iyi yorumlar NEDEN DEĞİLDİR. Bir keresinde kolayca sadeleştirilmiş gibi görünen karmaşık bir kod parçasına rastladım. Yorum, neden açıkça sadeleştirmenin bu özel durumda işe yaramadığını açıkladı (çünkü orijinal geliştirici zaten denemiştir).
Dan Pichelman

6
There are many questions on whether comments are good or bad, but no one that addresses the specific question of what are good examples of comments that tell you WHY. Herkes geçerli bir örnek verirse, hepsi doğru cevaplardır. Bu web sitesinin formatı, tüm cevapların eşit yaratılmadığı bir soru-cevap sürecini kolaylaştırmak içindir.
David Kaczynski

İyi nokta, @ david-kaczynski. Sen ne önerirsin?
rick

1
Başımın üstünde, soruyu ifade etmenin bir yolunu düşünemiyorum, böylece tek bir örnek veya genelleştirilmiş bir taktik "en iyi" cevap olabilir. P.se'nin bir sohbet bölümü var: chat.stackexchange.com/rooms/21/the-whiteboard , ancak muhtemelen sorunuzla ilgili olarak daha iyi bir forum olacaktı. Adil olmak gerekirse, sorunuz buradaki topluluktan olumlu bir yanıt alıyor gibi görünüyor, bu yüzden muhtemelen endişelenmeye değmez. Yararlı yorumların örneklerini bulmak için verebileceğim en iyi tavsiye popüler halk git depolarına göz atmak olacaktır.
David Kaczynski,

Yanıtlar:


62

En yaygın ve en belirgin örnek, çeşitli geçici çözümler hakkındaki yorumlardır. Örneğin bu bir:

https://github.com/git/git/blob/master/compat/fopen.c :

/*
 *  The order of the following two lines is important.
 *
 *  FREAD_READS_DIRECTORIES is undefined before including git-compat-util.h
 *  to avoid the redefinition of fopen within git-compat-util.h. This is
 *  necessary since fopen is a macro on some platforms which may be set
 *  based on compiler options. For example, on AIX fopen is set to fopen64
 *  when _LARGE_FILES is defined. The previous technique of merely undefining
 *  fopen after including git-compat-util.h is inadequate in this case.
 */
#undef FREAD_READS_DIRECTORIES
#include "../git-compat-util.h"

Git ve Linux kaynaklarında kesinlikle daha fazla örnek bulacaksınız; Her iki proje de bu kurala uymaya çalışır.

Ayrıca bu kuralı daha kesin bir şekilde taahhüt günlükleriyle takip etmenizi de tavsiye ederim . Kod yorumları için kodu düzeltmiş olabilirsiniz, ancak yorumu güncellemeyi unutmayın. Her zamanki projedeki kod miktarı ile er ya da geç gerçekleşmesi garanti edilir. Diğer taraftan, işlem kaydı belirli bir değişime bağlıdır ve versiyon kontrol sisteminin "açıklama" / "suçlama" işlevselliği kullanılarak geri çağrılabilir. Yine Git ve Linux'un bazı güzel örnekleri var.

Örneğin, bu göreve bakın . (buraya kopyalamıyor, çok uzun). Neyin yanlış olduğunu, neyin yanlış olduğunu ve neyin yanlış olduğunu açıklayan ve tüm SIX satırlarını değiştiren dört sayfa paragraftan oluşuyor. Bunun gibi yorumları iki amaç için kullanırlar:

  1. Gönderilen tüm değişiklikler gözden geçirilir ve taahhüt günlüğü değişikliği gözden geçirene açıklamak zorunda olan şeydir.
  2. Bir hata bulunduğunda, ilgili günlükler daha önceki hatalı davranışlara geri dönülmemesi için "kazma" veya "suçlama" kullanılarak alınır.

(not: bu iki örnekle ortaya çıkmam için git repo'yu rastgele taramam en fazla 10 dakika sürdü, bu yüzden orada daha fazlasını bulmak kolay olurdu)


29

Kodun arkasındaki gerekçeyi neden açıkladığınızı açıklayan bir yorum - örneğin:

// We need to sync the values if the temp <doodad> GUID matches one of the active <doodad>'s
// GUID, as the temp <doodad> has the most recent values according to the server and said 
// values might have changed since we added the <doodad>. We want a user to be able to <foo> 
// the <doodad> whenever, which means those values must be accurate.
for (doodad in doodads) {
    if ([doodad guid] == [tempDoodad guid]) {
        [doodad updateFromDoodad:tempDoodad];
        break;
    }
}

Kodun ne yaptığını nasıl açıkladığınızı açıklayan bir yorum .

// Loop through our <doodads> and check for a GUID match. If it matches, copy the new values
// on the <doodad> that matches 
for (doodad in doodads) {
    if ([doodad guid] == [tempDoodad guid]) {
        [doodad updateFromDoodad:tempDoodad];
        break;
    }
}

Aradaki fark, bir bakıcı ilkine bakabilir ve "Ah, öyleyse bu güncel olmayabilir!" Diyebilir. İkinci durumda, söz konusu bakımcının size kodun gösteremediği hiçbir şeyi söylemediği bir yorumu vardır (iyi değişken isimleri varsayarsak).

İşte neden bir yorumun gerçek bir örneği, bir iOS kodundan, bir ağ geçidi adresi (veya bunun için makul bir tahmin) almak için ihtiyaç duyduğumuz yerde çalıştı. "Alış soketini başlat" gibi şeyler söyleyen yorumları bırakmış olabilirdim, ancak bu sadece bir bakıcıya (ya da geleceğe) neler olduğunu, neden geçit adresini almak için bu garip pisliği yapmak zorunda kaldığımı söyleyemezdi. ilk yer.

/*
 We're going to do something really hacky here and use a custom partial
 implementation of traceroute to get our gateway IP address.

 [rant removed - irrelevant to the point]

 There's no good way to get at the gateway address of an iDevice
 right now. So, we have two options (per https://devforums.apple.com/message/644915#644915 ):
 1. Get at and parse the routing table (like netstat -rn, or route -n)
 2. Do a traceroute and grab the IP address for the first hop

 As far as I can tell, the former requires <sys/route.h> from the Mac OS X
 header files, which doesn't seem like a good idea to me. Also, there's a
 thread on the Apple Developer forums that seems to imply that header isn't
 in iOS for a reason (https://devforums.apple.com/message/774731#774731 ).

 So when we send our request with a TTL of one it will survive a single hop
 to the router and return, triumphant, with the router's IP address!

 Viva la kludge!

 PS: Original source was the below SO question, but I've modded it since then.
 http://stackoverflow.com/questions/14304581/hops-tracing-ttl-reciveform-on-ios/14304923#14304923
 */

// Default to using Google's DNS address. We used to try checking www.google.com
// if reachability reported we had internet, but that could still hang on routers
// that had no internet connectivity - not sure why.
const char *ip_addr = [kGoogleDNS UTF8String]; // Must be const to avoid undefined behavior
struct sockaddr_in destination,fromAddr;
int recv_sock;
int send_sock;

// ... more code follows

4
İlk örnek aşırı derecede ayrıntılı ve "nasıl" nın çoğunu içeriyor. Sadece "<doodads> 'ı temp <doodad>' dan güncelleyin, böylece kullanıcı istediği zaman güvenle <foo> yapabilir." Gerisi bundan veya koddan bahsetmek açısından önemsizdir. Ayrıca son örneğin ilk dört paragrafındaki "masal giriş" tamamen anlamsızdır. "Viva la kludge!"; komik ve sonunda. Ancak başlangıç, gerçek açıklamaya başlamadan önce kazılması gereken çok fazla kelime.
Jan Hudec,

@JanHudec Geri bildiriminize göre ayarlandı. Şuna bak.
thegrinner

15
İkinci örnekle ilgili güzel şeylerden biri, yalnızca kodun neden belirli bir şekilde çalıştığını açıklamak değil, aynı zamanda diğer makul alternatiflerin neden alınmadığını da açıklamaktır. Bu, kodu çok daha bakımlı hale getirir, çünkü kodu okuyan ve "Neden yönlendirme tablosunu ayrıştıramıyorum?" sadece yorum okuyabilir. Ayrıca, kodu değiştirmek için meşru bir neden bulmuş olan biri , bunu yapmanın güvenli olacağından emin olacaktır. Aksi halde, bir bakımcı, çamurun ilham verdiği (bilinmeyen) senaryoda herhangi bir değişikliğin başarısız olacağından korkuyor.
Brian

18

Cevaplarıma Jeff Atwood tarafından Blog yazı kodunda yapılan bir alıntı ile başlamak istiyorum. Size Nasıl Olduğunu, Yorumlar Nedenini Söyler :

En iyi yorum türü, ihtiyacınız olmayan yorumlardır.

Ayrıca şunu belirtir:

İlk önce kodunuzu, bir koltuk değneği olarak yorumlara güvenmeden anlamak için mümkün olduğunca basit hale getirmek için çaba göstermelisiniz. Yalnızca kodun anlaşılmasını kolaylaştıramayan bir noktada yorum eklemeye başlamanız gerekir.

Tamamen katılıyorum ve bu noktada, kodu olabildiğince basit hale getirmeye başlamadan önce kodun çalışmasını ve sonra yeniden düzenlemeye başlamam gerektiğini eklemeliyim. Yani yeniden yapılanmaya başlamadan önce ilk çalıştırmada yorumların neden çok yardımcı olduğunu ekleyerek .

Örneğin, verileri ayrıştırırken haftanın günleri tablosunu doldurmak için 2 boyutlu hastable içeren 3 yuvalanmış döngü kullanıyorsanız, birkaç hafta boyunca bakılmadığı ve aniden yeniden bakılmadığı takdirde, bir başkasının ne yaptığını takip etmek çok kolaydır.

[loop1]6oclock -> [loop2]Monday -> [loop3]stage 1 to 4
         -> tuesday-> stage 1 to 4
         ...
         -> Saturday -> stage 1 to 4
    7oclock -> Monday-> stage 1 to 4
        ....etc.

Üst bölüm, iç içe geçmiş 3 döngünün yeniden yapılanmadan önce nasıl çalışacağının bir örneğidir.
Ayrıca bazı branş koşullarının açıklanması, süreçte ne düşündüğü konusunda kodun daha iyi anlaşılmasına yardımcı olabilir:

// added a zero before the actual day in order for the days always to be 2 digits long.
if( actualDayFuture < 10 ) 
{ 
     actualDayFuture = padIfSingleDigitDate(actualDayFuture); 
}

Basit ve açık kodlar bile yorumlar ile uyumludur. Sadece işleri daha açık, net veya daha anlaşılır hale getirmek için iş arkadaşlarınız için ve hatta yazılımın korunmasında kendiniz için anlaşılması.

Tabii ki, xp devletlerinin kendi kendini açıklayan bir kodu olduğundan emin olun, ancak bir satır yorumu acıtıyor mu?

Ayrıca bu blogdan şu kuralları çok faydalı buluyorum :

  • Yazmadan önce materyali anlama
  • Hedef kitleniz dördüncü sınıf öğrencisi gibi yazın
  • Okuyucuların sizi nasıl yanlış anlayabileceklerini düşünün

Kendi koduna geri dönmek zorunda olan ya da bir başkası, hatta eski kodunu geri almak zorunda olan herkes bunun baş ağrısı olabileceğini bilir. Bu yüzden tembel olmak ya da çok az veya hiç bir şey hakkında yorumda bulunmama konusunda uber-kodlayıcı olmaya çalışmak yerine, neden belirtilen kurallara uyarak gelecekteki yaşamınızı kodunuzu korumak zorunda bırakan kendinize veya bazı zavallı böceklere sahip olmuyorsunuz?

Ayrıca birçok programlama kararları gözden geçirme sırasında şüphe edilir ve kodun yıllar geçtikçe kullanıldığı gibi bulunan büyük bir hata nedeniyle bir programın çalışması için hayati öneme sahip olsalar bile, bazı bölümlerin neden bu kadar önemli olduğu gibi yazıldığından her zaman açık değildir. . Bu yüzden hepinizi bir tl ile tamamen sıkmamak için; acmqueue'dan son bir alıntı ile yakın :

Öncelikli, açık ve kapsamlı dokümantasyon, hayatta kalabilen ve uyum sağlayabilen bir yazılım yaratmada kilit bir unsurdur. Yüksek standartlara göre belgelemek geliştirme süresini kısaltacaktır, daha iyi çalışmayla sonuçlanacak ve sonuçta iyileşme sağlayacaktır. Herhangi bir teknikten daha fazlasını istemek zor.


8
İkinci örneğinizde, yeniden gözden geçirme ile yorumları tamamen ortadan kaldırabiliriz: actualDayFuture = padIfSingleDigitDate (actualDayFuture); Bu önemsizdir, ancak daha sağlam bir örnek bu yaklaşımdan fayda sağlayacaktır.
Chris Cudmore

4
Şartlıyı da yönteme dahil ettim. - Yine, çok önemsiz bir şey için değil, ama tamamen dolgu mantığı hakkında düşünmemeyi sağlar. Asıl örneğinizin yerini almam, çünkü sorunun cevabı daha iyi. Diğer alternatifleri keşfederek daha fazla not aldı.
Chris Cudmore

1
Reklam "xp’in kendi kendini açıklayan, ancak tek satırlık bir yorumun zararı var mı?" Olduğunu belirtir. ": Yorumlar iyi, ancak aşırı yorum yapma tehlikesi de var. Her yorum satırı, birinin kodu değiştirdiğinde güncellemeyi unutabileceği bir satırdır.
Jan Hudec,

1
Bunu söylemenin daha iyi bir yolu "En iyi yorum türü, yorum yapma gereğinin olmamasıdır" dır. Gerekli olmayan (ancak yine de yazılan) yorumlar iyi yorumlar değildir.
Kaz

1
Başvurulan kodun int directionCode = (x > oldX) ? DIRECTIONCODE_RIGHT : (x > oldX) ? DIRECTIONCODE_LEFT : DIRECTIONCODE_NONE;hatalı olması ilginç . Kesinlikle olmalı ... (x < oldX) ? DIRECTIONCODE_LEFT : DIRECTIONCODE_NONE;. İyi yorum fikirleri - kötü kod.
chux

8

Belli bir fonksiyonelliğin / kodun daha ayrıntılı bir şekilde açıklandığı referanslara ya da belirli bir programlama yolunun neden seçildiğini açıklamaya yönelik yorumları azaltma eğilimindeyim.

Benzer becerilere sahip diğer programcıların kodunuzu kullandığını veya okuduğunu göz önünde bulundurursak, bir şey elde etmenin beklenenden farklı bir yolunu kullanıyorsanız yorum yapmak önemlidir. Öyleyse bir yorumda neden bu yolu seçtiğinizi açıklayabilirsiniz.

Örneğin, bir Android cihazdaki iki farklı sensörü kullanabilirseniz ve bunlardan biri ihtiyaçlarınızı karşılamıyorsa, diğerinde neden birini seçtiğinizi açıklayabilirsiniz.

Yani 'Neden' bir vermelidir gerekçe yapılan seçimlere.


5
Referanslar harika bir örnek. // Bu yöntem foobit'i sıralamak için furshclingeheimer algoritmasını kullanır. Http: // ...
Chris Cudmore

8

Yorumlar, kodun ne yapmadığını, mutlaka WHY , HOW veya WHAT tarafından sınırlandırılmaması gerektiğini söylemelidir . İyi isimleriniz varsa ve iyi tanımlanmış işlevleriniz varsa, kodun size tam olarak ne olduğunu söyleyebilmesi oldukça olasıdır. Örneğin:

List<LightMap> maps = makeLightmaps(receivingModels);
TrianglePartitioner partition = new Octree(castingTriangles);
List<Photon> photons = firePhotons(lights, partition);

if (photons.Count > 0)
{
      PhotonPartitioner photonMap = new KDTree(photons);
      gatherPhotons(maps, photonMap, partition, lights);
}

Bu kod gerçekten yorum gerektirmez. İşlev ve tür adları anlaşılmasını kolaylaştırır.

Bununla birlikte, bazen, yukarıdaki gibi gerçekten akıcı kodlar yapmak zor veya imkansız olabilir. Örneğin, bir sonraki kod pasajı, bir küre üzerinde istatistiksel olarak rasgele bir nokta bulmak içindir. Matematik oldukça opaktır, bu yüzden açıklamanın bağlantısını içeren bir yorum NASIL çalıştığını söylemektir . Bu, bir kereden fazla ihtiyaç duyulursa bir yoruma ihtiyaç duymadan Neyin yapıldığını söyleyen bir fonksiyona sarılabilir , aksi halde bağlantı başlığı da bu bölümde yardımcı olur.

double randomA = localGenerator.NextDouble();
double randomB = localGenerator.NextDouble();

//http://mathworld.wolfram.com/SpherePointPicking.html
double theta = 2 * Math.PI * randomA;
double phi = Math.Acos(2 * randomB - 1);

Vector3 randomDirection = new Vector3(Settings.ambientRayLength * (float)(Math.Cos(theta) * Math.Sin(phi)),
                                      Settings.ambientRayLength * (float)(Math.Sin(theta) * Math.Sin(phi)),
                                      Settings.ambientRayLength * (float)Math.Cos(phi));

Yorumlar size kodun ne olmadığını söylerken başka bir örnek bir kararı açıklamak içindir. Bir sonraki örnekte, kod, iş parçacığı olmayan bir yerel değişkeni, iş parçacığı bir kod parçası içinde kilitlemiyor. Bunun bir nedeni var ve yorum NEDEN açıklıyor . Yorum olmadan, bir hata olarak kabul edilebilir veya fark edilmeyebilir.

Random random = new Random();
Parallel.For(0, maxPhotons, delegate(int photonIndex, ParallelLoopState state)
{
    ...
    //I don't actually care if this random number is unique between threads, threadsafty is not that big of a deal
    //  in this case and locking the random object could cause a lot of lock contention
    while (random.NextDouble() > reflectProbability)
    {
        ...
    }
    ...
}

Muhtemelen, rastgele nesnenin neden ilk önce paralel döngü içinde yaratılmadığını söylemek iyileştirilebilir. Sebep yoksa, biri gelip tüm fikrin aptalca olduğunu ve yeniden yapılanma için iyi bir yer olduğunu fark edebilir.


Yorumların öncesinde zaman yorumlarınızı gerektirmiyor kodunu açıklamak için makul mi WriteTextziyade //?

1
Cevapta söylediğim gibi, baskı beyanı olmasa bile yorumlar gerekli değildir, ancak noktayı daha net hale getirmek için baskı ifadelerini kaldırmak üzere düzenlemiştim.
Chewy Gumball

5

Farklı "neden" türlerini tanımak faydalı olabilir - en önemlisi:

  • Aşırı karmaşık görünen kodun basitleştirilmiş olması durumunda işe yaramayacağının sebepleri (örneğin, bazı köşe durumlarda kodun çalışmasını sağlamak için gereksiz görünüşte olan bir tahmin) gerekebilir).

  • Tehlikeli görünen belirli bazı basit işlemlerin gerçekten güvenli olma nedenleri (ör. "Getirme verileri rutininiz, sonuncusu geçmişe ait herhangi bir şeyden daha az olduğu gibi kukla bir öğeyi ve bundan sonra gelen öğeyi; diğerinden önce, sürekli artan veya azalan bir dizide, onu izleyen en az bir tane daha (muhtemelen kukla) bir öğeye sahip olacak ").

Çoğu durumda, kodun bir kısmındaki ikinci tipin bir yorumu diğerinin ilk tipinin bir yorumuyla "eşleşebilir" (ör. "Bu işlem dizisi basitleştirilebilir gibi gözükse de Fitz rutinine güveniyor. Wongle, Bandersnatch Blarped'ine kadar uyandırana kadar Woozled değil. ")


2

Unutma, eğer bir program yazıyorsan, sadece rastgele şeyler yazmazsın, yaparsın, çünkü istediğin bir modelin var , ister resmi bir belgede olsun, ister kafanda. Kafanızdaki şeyler her bit bilgisayardaki bir yazılım / veri kadar gerçektir (ve sadece böcek içerme olasılığı yüksektir).

Kodunuzu okuyan birisinin kafasında o model olmayabilir, bu nedenle yorumlar onlara modelin ne olduğunu ve kodun onunla nasıl ilişkili olduğunu söylemeye yarar. Bence "neden" ile kastedilen budur. Elbette kodun kendisini olabildiğince açıklayıcı hale getirmesi iyi, ama bu her zaman yeterince iyi değil. Örnek:

// transform the x,y point location to the nearest hexagonal cell location
ix1 = (int)floor(0.5 + x + y/2);
iy1 = (int)floor(0.5 + y);

Bunun üzerine, model zamanla değişir ve bu değişikliklerin koda aktarılması gerekir. Bu nedenle, yorumların yalnızca bir şeyin kodda "neden" olduğunu değil, aynı zamanda beklenen model değişikliklerine yanıt olarak nasıl değiştirileceğini de söylemeleri gerekir . Örnek:

// to change to square cell locations, remove the "+ y/2" in the above code

Bence yorumların amacı bazen göz ardı ediliyor.


2
Soru örnekler istiyor. Bu cevabı daha kullanışlı hale getirmek için bir örnek ekleyebilir misiniz?
Bryan Oakley

2
İlk kod öbeği bana "neyi" açıklamanın klasik bir örneğine benziyor. Kötü bir yorum değil, ancak OP'nin sorusuna cevap verdiğini sanmıyorum.

@Jon: Yorum orada olmasaydı, okuyucu ne olduğunu görebilir ancak neden olduğu hakkında hiçbir fikri yoktur.
Mike Dunlavey,

1
@ MikeDunlavey: Ben katılmıyorum. Hala bir fikrim yok - neden en yakın altıgen hücre konumunu istiyorsun? Bu yeri almanın amacı nedir ? Bu iki satırı silsem herhangi bir şeyi etkiler mi?

2

Yorumlarımın hepsi 'neden' türünde değil, birçoğu.
Bunlar bir (Delphi) kaynak dosyasından örnekler:

// For easier access to the custom properties:

function GetPrivate: Integer;   // It's an integer field in the external program so let's treat it like that here

// The below properties depend on the ones above or are calculated fields.
// They are kept up-to-date in the OnEventModified event of the TTSynchronizerStorage
// or in the ClientDataSet.OnCalcFields of the TcxDBSchedulerStorage.DataSource.DataSet
property IsModified       : Boolean   read GetIsModified   write SetIsModified;
property IsCatTT          : Boolean   read GetIsCatTT      write SetIsCatTT;
property IsSynced         : Boolean   read GetIsSynced     write SetIsSynced;

lLeftPos := pos(' - [',ASubject); // Were subject and [shiftnaam:act,project,cust] concatenated with a dash?

// Things that were added behing the ] we will append to the subject:

// In the storage the custom value must also be set for:
Self.SetCustomFieldValueByname(cCustFldIsCatTT,Result);

// When we show the custom fields in a grid, the Getters are not executed,
// because the DevEx code does not know about our class helpers.
// So we have two keep both properties synchronized ourselves:

// lNewMasterEvent was set to usUpdated, overwrite because we added:
if ARepair then
  lNewMasterEvent.CustUpdateStatus := usRecreated

// The source occurrence date may have bee changed. Using GetOriginalDate we can retrieve the original date,
// then use that for creating a target occurrence (and update its date):

lNewTTOccurrence.CustSyncEntryID := cSyncEntryID0;    // Backward compatibility with old sync methode

// Single event became recurring or vice versa; replace entire event

// In contradiction to CopySingleEventToTimeTell, CopyMasterEventToTimeTell does not have a ANewStatus parameter
// because master events are always added.

(Benim) neden yorumlar genellikle bunu yapacak olan koddan önce gelir (bu nedenle iki nokta üst üste).

Bazılarının sadece neler olduğunu açıklayan yorumlarım var , örneğin bir süreç mantıksal bir gruplandırmaya sahip birçok adım olduğunda (ve kodun bunu otomatik olarak gösterecek şekilde düzeltilmemesi durumunda), şöyle bir yorumda bulunacağım:

// Step 1. Initialization

1

Niçin bir şeyi garip ya da belki de mantıksız bir şekilde yapmanın sebebi olarak anlıyorum, böyle yapılmasını gerektiren şartlar nedeniyle. NASIL kodu hayır "mantıklı" yapar bile olursa olsun ne kadar tuhaf kod kendisi görülebilir. NE muhtemelen en iyi sınıf / fonksiyon belgelerin başında anlatılıyor. Böylece ekleyerek bırakır işe NEDEN nedeniyle kontrolünüz dışında nedenlerle Eğer yapılması gereken nasıl ve hangi ve tuhaf şekillerde yer almayan şey açıklamaz.

Tabii ki, her zaman durum böyle değil, tek boynuzlu atlar ve gökkuşakları ülkesi dışında ...

NASIL:

foreach($critters as $creature) {
   $creature->dance();
}

NE:

/* Dancing creatures v1.0
 * 
 * The purpose of this is to make all your critters do the funky dance.
 */

foreach($critters as $creature) {
  $creature->dance();
}

NEDEN:

// We had to store the items in an array of objects because of _____ (reason)
foreach($critters as $creature) {
   $creature->dance();
}

5
Bu soruyu soruyu nasıl cevaplıyor?
tatarcık

1
OP'den alıntı yapmak için: "Öyleyse, soruya geri dönün: yorumlar size NEDEN söylese, neden bu kadar niçin bahsettiğimizi?", Ve ben şu soruyu cevapladım: konuşulan NEDEN, varlığın gerekçesi verilen kod parçası.
Juha Untinen,

1
Soru özellikle örnekler için birkaç kez sorar. Daha kullanışlı hale getirmek için bu cevaba bir örnek ekleyebilir misiniz?
Bryan Oakley

1
Bu yorumlardan herhangi birinin aslında yardımcı olduğunu sanmıyorum. Eğer fonksiyonunuzun imzası critters.dance()öyleyse, yorum sadece açıkça tekrar eder ve “Çalıştığımız herhangi bir şekilde çalışmasını sağlayamadık” tamamen yararsızdır. Ayrıca, “her nesne için yöntemi arayacağız” demek, kodun çok açık bir şekilde söylediğini tekrarlamaktır.
Brendan Long,

1

HER ZAMAN C ++ başlık dosyalarına yorum yazmayı öğrendim (çünkü isminin iyi bir ipucu vermesine rağmen, bir fonksiyonun NEDEN her zaman net olmadığı her zaman açık değildir).

Bana göre tipik bir yorum gibi görünüyor

/*** Functionname
/*   What happens here
/*  [in] Params
/*  [out] params
/*** 

NEDEN yorumlar kullandığım tek zaman, "BU BU DOKUNMAYIN! Çünkü ..." veya "PROGRAM HATASI SİLECEĞİNDE ÇARPILACAK ..."

Geçici çözümler, kesmek ve garip davranış gözlerimdeki NEDEN kriterlere uygundur

Çok iyi ve hatta çok komik bir örnek, Richard adlı bir kişi tarafından yazılmış bazı karışık kodlar için bu "geçici çözüm" dür, başkası onu sardı ve açıklamalarda nedenini açıkladı ... https://stackoverflow.com/a/184673/979785

Ne yazık ki, boğa sarmak zorunda kaldığınız epeyce zamanlar var, çünkü orjinaline dokunamıyorsunuz, çünkü "her zaman böyle olmuştur" ya da erişiminiz yok ya da ... Orijinali düzeltmek için zamanınız yok, bu amaç için ek yüke gerçekten uygun değil.


7
Bunun dışında soru yorumlarla ilgili , dokümantasyon değil . Onlar aslında farklı şeylerdir ( documentationetiket üzücüdür ancak yine de soruya uygulanmaz).
Thomas

Özür dilerim, anadil yorumumda ve dökümantasyon yorumumda birbirinin yerine kullanıldığını ve bu yüzden bu soru için de geçerli olduğunu düşündüğüm etiketle birlikte kullandım. Bu gerçekten düşürmek için bir neden mi?
AnyOneElse,

2
Sorusu örnekleri için birkaç kez sorar neden yorumların, ancak dahil tek örnek bir olduğunu nasıl açıklama. Örneklerin cevaplarını inceleyen insanlar, örneğinize göre yanlış yönlendirilmiş olabilir. Neden bir yorum örneği verebilir misiniz ?
Bryan Oakley

Her ne kadar kodumda çok az sayıda WHY olduğunu söylesem de, iki örnek verdim: EDITED ... işte kesinlikle bir WHY için uygun olan bir bağlantı
AnyOneElse

@AnyOneElse Oy vermedi. Ben gelmeden önce oradaydı.
Thomas

0

Kodun yürütme planını belirtmesi gerekiyordu. Bu şekilde program takipçisi (veya derleyici) ne yapacağını ve nasıl yapacağını çözebilir. Program izleyicinin izleyebileceği adımlara ayrılan şey. İlkel adımlar nasıldır?

Kodlayıcının amacı başka bir konudur. Basit, anlaşılır, anlaşılır kodda amaç açıktır. Makul düzeyde yetkin herhangi bir insan okuyucu, sadece kodu okuyarak bir kod bloğunun amacına ulaşacaktır. Kodların çoğu böyle okumalı.

Bazen, niyet ile plan arasındaki ilişki belirsizdir. Kod neyi ve nasıl olduğunu açıklıyor, fakat sebebini değil. O zaman niyeti açığa vuran yorumlar değmeye değer. Programcının amacı budur.


3
Soru, örnekler için birkaç kez sorar. Daha kullanışlı hale getirmek için cevabınıza bir örnek ekleyebilir misiniz?
Bryan Oakley

0

Bu konuyu şu anda saklamak, karmaşık ve biraz sarsılmış bir veri modeline karşı saklı yordamlar ve görüşler arasında dolaşıyor.

"X.account boş olmadığı zaman ve x.adresi içeri girdiğinde (fedex adresini seç) durumunda", sonra x.account başka bir y.account sona erdiğinde) ve seçimlerimiz tamamlandı; Tüm kaynak kodunu okumak için. Ve bu tür bir çeşit mantıklı geliyor, ama yine de anlaşılmaz.

Neden fedex'te o zaman x ve o zaman değilse y - tüm sisteme ışık tutuyor ve yeterince okuduğumuzda bunu almaya başlıyoruz. Ve bu bitti basitleştirilmiş ve yüzlerce veya binlerce benzer ifade var. Kalbim, 2007'den bu yana olan türden birinin neye benzediğini kimseye karşı sıcak bir şekilde parlıyor.

Yani evet, karmaşık kıvrımlı veri modelleri ve tüylü saçakları ve birden çok geçerli olarak isimlendirilmiş yollarla saklı prosedür, lütfen Gd aşkı bize nedenini söyle.


0

Ben sadece bu yorumu yazdım; Bir kod satırının neden ne olduğunu açıklamanın somut bir örneği ve özellikle de neden değiştirdiğimi açıklıyor.

Yöntem depolanan verileri inceler ve bir ucunda bugünün tamamında ve diğer ucunda başlangıç ​​tarihi boyunca tamamlanmış olup olmadığını değerlendirir.

// In principal, this should be ">=", as we may have data up to the account start
// date but not complete for that day; in practice, 98% of the time if we have
// data for the start date it *is* complete, and requerying it would be a waste
// of time.
while (endDate > accountStartDate)
    ...

Tahmin edebileceğiniz gibi, operatörden daha büyük olan operatör büyük veya eşit olmuştur. Yorum, eski değerin neden anlamlı olduğunu ve yeni değerin neden daha iyi olduğunu açıklar. Gelecekte buna bakacak olursa, ">" kullanımının bir gözetim değil, bir optimizasyon olduğunu göreceklerdir. Daha sonra, ihtiyaca göre değiştirebilir veya bırakabilirler.

Sitemizi kullandığınızda şunları okuyup anladığınızı kabul etmiş olursunuz: Çerez Politikası ve Gizlilik Politikası.
Licensed under cc by-sa 3.0 with attribution required.