Programlamaya makul miktarda zaman harcarsanız, karşılaşacağınızdan emin olabilirsiniz. kod yorumları. Hatta bazılarını kendin yazmış olabilirsin. Bu küçük metin parçaları programın içine yerleştirilmiştir, ancak derleyici veya yorumlayıcı tarafından göz ardı edilirler. Kodla çalışan insanlara yöneliktirler ve birçok uygulamaları vardır. Hatta kodunuzu yeniden şekillendirebilir veya başkaları için otomatik olarak belgeler oluşturabilirler. Bunları nasıl doğru bir şekilde kullanacağınızı bilmek ister misiniz? O zaman doğru yerdesiniz!

Yorumları, nasıl kullanılacağını ve ayrıca nasıl kullanılacağını keşfetme zamanı değil onları kullanmak için.

Ne Öğreneceksiniz?:
Bu makaleyi okuyarak şunları öğreneceksiniz:

• Yorum nedir, türleri ve nasıl kullanılacağı.
• Nerede başladıklarını ve şimdi nerede olduklarını.
• İyi ve kötü yorum arasındaki fark.
• Geçmişten ve günümüzden pratik uygulamalar.

Makalenin sonunda, kod yorumlarının neden önemli olduğunu, etkili yorumlar yazmak için en iyi uygulamaları, kaçınılması gereken bazı yaygın tuzaklar ve hataları ve otomatik belge oluşturucular da dahil olmak üzere kod yorumlama sürecinizi optimize etmek için kullanabileceğiniz araç ve kaynakları öğreneceksiniz. , yorum satırları ve kod inceleme platformları.

Kod yorumlarının ne olduğuna derinlemesine bir bakışla başlayacaksınız.

Kod Yorumları Nedir?

Yorumlar bir yazılım programı içinde, programcıların kodun ne yaptığı hakkında bilgi sağlamak için ekledikleri, insanlar tarafından okunabilen ek açıklamalardır. Yorumlar, programlama diline ve yorumun amacına bağlı olarak birçok biçimde olabilir.

İki türe ayrılırlar: blok yorumları ve satır yorumları.

• Yorumları engelle Yorumun başında bir karakter dizisi ve sonunda başka bir karakter dizisi kullanarak kod içindeki bir bölgeyi sınırlayın. Örneğin, bazı kullanımlar /* başlangıçta ve */ sonunda.
• Satır yorumları derleyiciden yorumun başlangıcından satırın sonuna kadar her şeyi yok saymasını istemek için bir dizi karakter kullanın. Örneğin: #, – or //. Satır yorumlarının nasıl belirtileceği kullandığınız programlama diline bağlıdır.

İşte her tür yorumun Swift'te nasıl göründüğüne dair bir örnek:

struct EventList: View { // BU BİR SATIR YORUMU @EnvironmentObject var userData: UserData @EnvironmentObject var eventData: EventData /* BU BİR BLOK YORUMU @State private var isAddingNewEvent = false @State private var newEvent = Event() */ var gövde: biraz Görünüm { ... } }

Bazı programlama dilleri yalnızca bir tür yorum sırasını destekler ve bazıları bir sıranın çalışması için geçici çözümler gerektirir. Bazı diller yorumları şu şekilde işler:

Yapışkan notu nasıl kullanacağınızı düşünün. Programcılar için yorum, sınırsız kullanımı olan yapışkan bir nottur.

Kullanımları genişledikçe ve standartlaştıkça yorumlar zaman içinde daha fazla önem kazanmıştır. Bu makalede bu kullanımların çoğu hakkında bilgi edineceksiniz.

Yorumun Kısa Tarihi

Kısa bir süre önce bilgisayarlar ekran ve klavye kullanılarak programlanmıyordu. Delikli kartlar kullanılarak programlandılar: bir bilgisayar için talimatları belirtmek üzere sırayla delinmiş delikleri olan küçük sert kağıt parçaları. Bunlar, bir okuyucuya beslenen dev yığınlar haline gelecek ve bilgisayar programı çalıştıracaktı.

Her bir kartın veya bir kart setinin ne işe yaradığını bir bakışta anlamak zordu. Bunu çözmek için programcılar üzerlerine notlar yazardı. Bu notlar, yalnızca karttaki delikleri okuduğu için makine okuyucusu tarafından göz ardı edildi. İşte bir örnek:

Bugün çoğu yorum aynı amaca hizmet ediyor: kodun ne işe yaradığını anlamaya yardımcı olmak.

Yorumsuz Kod

Programcılar arasında yaygın bir söz, “İyi kodun açıklamaya ihtiyacı yoktur” şeklindedir. Bu bir dereceye kadar doğrudur ve bazı programcılar kodlarına yorum yazmazlar.

Ancak bu kod gerçekten büyüdüğünde ne olur? Yoksa birkaç iş kuralı ve mantığı mı içeriyor? Yoksa başkalarının kullanması mı gerekiyor? Yorumlanmayan kodu deşifre etmek mümkün olabilir, ancak zaman ve çaba olarak ne pahasına?

Sürekli olarak kod yazmaya odaklandığımızda, söz konusu kodu yazdıktan birkaç ay, hatta birkaç hafta sonra, mantığın çoğunun hafızamızdan çıktığını unutuyoruz. Neden belirli seçimler yaptık? Neden belirli kuralları kullandık? Yorumlar olmadan, ne düşündüğümüzü anlamaya yönelik pahalı alıştırmalardan geçmek zorunda kalacağız.

Yorumlar inanılmaz derecede faydalıdır ve iyi geliştiriciler bunları kullanmalıdır. Ancak, tüm yorumlar eşit yaratılmamıştır. İşte yorumları neyin iyi, işe yaramaz ve hatta verimsiz yaptığına bir göz atın.

İyi Yorumlar

İyi yorumlar basit ve okunması kolaydır. Kodun nasıl çalıştığının aksine bir düşünce zincirini netleştirir veya belirtirler.

Ek açıklamalar, kaynaklara bağlantılar ve alıntılar, lisanslar, bayraklar, görevler, komutlar, belgeler vb. gibi birçok biçim alabilirler.

Yararsız Yorumlar

Yorumlar iyi, ancak bunları kullanmanıza gerek yok her yerde. Yaygın bir hata, zaten açık olan kodun ne yaptığını açıklamak için yorumları kullanmaktır.

Örneğin, bir dizide yinelenen ve her değeri artıran bir kodunuz varsa, bunu açıklamaya gerek yoktur - kodu gözden geçiren programcı için aşikâr olmalıdır. Ne değil bariz olsa da, neden bunu yapıyorsun Ve iyi bir yorumun açıklayacağı şey de budur.

Bariz olanı açıklamak yaygın bir hatadır… ve bunu yapan yorumlar sadece yer kaplıyor ve potansiyel olarak kafa karışıklığına neden oluyor.

Kötü Yorumlar

Kötü yorumlar yararsız olmaktan çok yıkıcıdır. Karışıklığa neden olurlar veya daha kötüsü, dolambaçlı veya kötü yazılmış kodları mazur görmeye çalışırlar. İyi kodun yerine yorumları kullanmaya çalışmayın. Örneğin:

var n = 0 // Satır numarası

Bunun yerine şunları yapın:

var satırNumarası = 0

TODO, BUG ve FIXME yorumlarıyla kodu karıştırmak gibi yorumları kötüye kullanmak kötü bir uygulamadır. En iyi çözüm, bir ekip üzerinde çalışırken kod işlemeden önce bunları çözmek veya yalnızca bir çağrı sisteminde bir sorun oluşturmaktır.

Yorumlar serbest biçimli olduğundan, bir yorumun nasıl görünmesi gerektiğini belirlemek için bazı kurallara veya şablonlara sahip olmak yararlı olur, ancak kuralları karıştırmak kötü yorumlar kategorisine girer.

Geliştirme sırasında kod hakkında yorum yaptınız mı? Taahhüt etmeyin - ekipteki diğer kişilerin kafasını karıştırmadan önce sorunu çözün ve yorumu kaldırın.

Açıklamaların Ötesinde

Bu noktaya kadar, yorumları açıklama olarak kullanmayı öğrendiniz. Ancak, yorumların önceden tanımlanmış bir formatı olmadığından, mütevazi yorum ek açıklamanızı bir veri dosyasına veya özel belgeye dönüştürerek kullanımlarını genişletebilirsiniz. İşte bazı iyi örnekler.

LİSANS Yorumları

LİSANS kodun şartlarını ve koşullarını belirten bir yorum türüdür. Bunları özellikle açık kaynak kodunda sıklıkla göreceksiniz. İşte MIT LİSANSINDAN bir örnek:

/* YAZILIM, SATILABİLİRLİK, BELİRLİ BİR AMACA UYGUNLUK VE İHLAL ETMEME GARANTİLERİ DAHİL ANCAK BUNLARLA SINIRLI OLMAMAK ÜZERE AÇIK VEYA ZIMNİ HİÇBİR GARANTİ OLMAKSIZIN "OLDUĞU GİBİ" SAĞLANIR. YAZARLAR VEYA TELİF HAKKI SAHİPLERİ HİÇBİR DURUMDA, YAZILIMDAN VEYA YAZILIMDAN VEYA YAZILIMDAN VEYA YAZILIMDAN, YAZILIMDAN, YAZILIMDAN, KULLANIMDAN VEYA DİĞER ANLAŞMALARDAN KAYNAKLANAN, BİR SÖZLEŞME EYLEMİ, HAKSIZ YA DA DİĞER HİÇBİR İDDİA, ZARAR VEYA DİĞER YÜKÜMLÜLÜKLERDEN HİÇBİR DURUMDA SORUMLU OLMAYACAKTIR. YAZILIM. */

Yorumlar serbest biçimli olduğundan, yorumun yazılma şekli birçok şekil alabilir. İşte Apple'dan bir örnek:

//===--------------------------------------------- ------------------===// // // Bu kaynak dosya, Swift açık kaynak projesinin bir parçasıdır // // Telif Hakkı (c) 2015-2016 Apple Inc. ve Swift proje yazarları // Çalışma Zamanı Kitaplığı İstisnası ile Apache Lisansı v2.0 altında lisanslanmıştır // // Lisans bilgileri için http://swift.org/LICENSE.txt adresine bakın // http://swift.org/ adresine bakın Swift projesi yazarlarının listesi için CONTRIBUTORS.txt // //===--------------------------------- ------------------------------===//

GEÇİCİ KOD ÇIKIŞI Yorumlar

programcılar kullanır GEÇİCİ KOD ÇIKIŞI hata ayıklama için bir araç olarak yorum yapın. Derleme işleminden bir blok veya kod satırı alarak, hangi kodun yürütülüp hangilerinin yürütülmeyeceğini değiştirebilirsiniz. Bu yöntem, genellikle bir eleme işlemi hata ayıklaması yapılırken kullanılır. Örneğin (yalnızca iOS için derleme):

let package = Package( name: "CommentOut", platformlar: [ .iOS(.v14), /* .tvOS(.v14), .watchOS(.v7), .macOS(.v11) */ ], ürünler: [ .library(ad: "CommentOut", hedefler: ["CommentOut"]) ], hedefler: [ .target(ad: "CommentOut") ] )

DEKORATİF Yorumlar

A DEKORATİF or AYIRICI yorum, bir dosyayı veya kod bloklarını bazı kategori veya işlevlere göre ayırabilir. Bu, kullanıcıların kodu daha kolay bulmasına yardımcı olur. İşte bir örnek:

/********************************************** * * Huffman Uygulama Yardımcıları * ****************************************** ******/

MANTIK Yorumlar

MANTIK yorumlar, kodu oluştururken seçtiğiniz mantığı belgeler. Bu, "Atanan bu değer neydi?" gibi kodun gösterdiğinin ötesine geçer.

Örneğin (dan hızlı paket yöneticisi/Kaynaklar/Komutlar/SwiftRunTool.swift, satırlar 287-288):

private func execute(yol: String, args: [String]) throws -> Never { #if !os(Windows) // Windows dışındaki platformlarda, SIGINT'i DispatchSourceSignal tarafından işlemek için Signal(SIGINT, SIG_IGN) kullanılır, // ancak bu işlem exec tarafından değiştirilmek üzeredir, bu nedenle SIG_IGN varsayılana döndürülmelidir. signal(SIGINT, SIG_DFL) #endif try TSCBasic.exec(yol: yol, args: args) }

Bu durumda, execute işlev, sinyal çağrısını içerecek veya atlayacak derleme koşullu yönergeleri içerir. Yorum, bunu neden yaptığına dair açıklamayı içerir.

Gelişmiş Yorum Formları

Yorumlar, tipik olarak tıpkı bir veri dosyası gibi biçimlendirilmiş özel içeriği tutabilir: kod içindeki bir dosya. Ayrıca, kaynak kodu çözümleyici araçlarının farklı şekillerde yanıt verebileceği basit bayraklar da olabilirler.

Yorumları İşaretle

bayrak yorumlar tipik olarak linterler tarafından kullanılır; özellikleri etkinleştirir veya devre dışı bırakırlar. SwiftLint'in bayrak açıklamalarını kullanarak özellikleri nasıl devre dışı bıraktığı aşağıda açıklanmıştır:

struct GitHubUserInfo: İçerik { izin ver: Dize // swiftlint: devre dışı bırak tanımlayıcı_adı izin ver avatar_url: Dize? // swiftlint: tanımlayıcı_adı etkinleştir }

Derleyicilerin kendileri de bir kurulum biçimi olarak bayrak açıklamalarını kullanır. Aşağıdaki örnekte, CLI betiği olarak ve UTF-8 biçiminde çalışan bir Python betiği görüyorsunuz:

#!/usr/bin/env python3 # -*- kodlama: UTF-8 -*-

not: Betiklerdeki ilk yorum satırının resmi bir adı vardır: the mesele. Amacı, komut dosyasını yürütürken işletim sisteminin hangi yorumlayıcıyı kullanması gerektiğini belirtmektir. Her zaman bir ile başlar #!.

GÖREV Yorumları

Tümleşik geliştirme ortamları (IDE'ler), metin editörleri ve bazı CLI araçları okuyabilir GÖREV programcılar tarafından gelecekte programcı tarafından gerçekleştirilecek bir eylemi belirten bir biçimde bırakılan yorumlar, örneğin YAPILACAKLAR:

// YAPILACAK: Model izinlerini değiştir // FIXME: Dizeleri Enum'a dönüştür

BELGE ÜRETİMİ Yorumlar

BELGE OLUŞTURMA yorumlar, bir aracın kaynak kodu ayrıştırmasına ve son kullanıcıların sınıflara, yöntemlere vb. göz atmak için kullanabileceği biçimlendirilmiş bir belge (genellikle HTML) çıkarmasına olanak tanır. İşte JavaDoc'tan bir örnek:

/** * @param string dönüştürülecek string * @param stringi * @param'a dönüştürülecek türü yazın elemanın türü * @param elemanın değeri */ V convert(Dize dizisi, Sınıf tip) { }

Diğer araçlar, IDE'ler tarafından görülen ve kod içinde kullanıcıya gösterilen belgeler oluşturabilir. Böyle bir araç Documentation Markup'tır (DocC). Bu, özellikle Apple'ın kendi kitaplıklarıyla kullandığı API'ler için kullanışlıdır. İşte açık kaynaklı SwiftGD projesinden bir örnek:

/// Görüntüyü, belirtilen tarama biçiminde "Veri" nesnesi olarak dışa aktarır. /// /// - Parametre formatı: Geri dönen görüntü verilerinin raster formatı (örn. jpg, png, ...). Varsayılan `.png` /// - Döndürür: Görüntü verisi /// - Gösterir: Belirtilen raster formatında `self` dışa aktarımı başarısız olursa `Hata`. genel işlev export(biçim olarak: ExportableFormat = .png) atar -> Veri { dönüş deneyin format.data(of: internalImage) }

CDATA Yorumları

CDATA yorumlar, biçimlendirilmiş verileri XML ve XHTML dosyalarına gömer. Bu yorumlarla, resimler, kod, XML içinde XML vb. gibi birkaç farklı tür kullanabilirsiniz:

John Smith ]]>

Wikipedia'nın makalesinden Bilgisayar Programlama Yorumları, sende KAYNAK dahil etme yorum türü: “ASCII sanat yapılarından oluşan logolar, diyagramlar ve akış şemaları, yorum olarak biçimlendirilmiş kaynak koduna eklenebilir”. Örneğin:

ClientApp (async_run, batch_process) | | V mru.ini (mru_history) ]]>

Yorumlarla Eğlenmek

Yorumların bir uygulamaya dahil edilmemesi, onlarla eğlenemeyeceğiniz anlamına gelmez. Hayat dersleri, şakalar, şiir, tic-tac-toe oyunları ve bazı iş arkadaşları şakaları, hepsini kod yorumlarına dönüştürdü. İşte py_easter_egg_zen.py'den bir örnek:

bunu içe aktar # Python'un Zen'i, yazan Tim Peters # Güzel, çirkinden iyidir. # Açık, örtük olmaktan daha iyidir. # Basit, karmaşıktan daha iyidir. # Karmaşık, karmaşıktan daha iyidir. # Düz, iç içe olmaktan iyidir. # Seyrek, yoğundan iyidir. # Okunabilirlik önemlidir. # Özel durumlar kuralları çiğneyecek kadar özel değildir. # Her ne kadar pratiklik saflığı yense de. # Hatalar asla sessizce geçmemeli. # Açıkça susturulmadığı sürece. # Belirsizlik karşısında, tahmin etme cazibesini reddedin. # Bunu yapmanın bir-- ve tercihen yalnızca bir -- bariz yolu olmalıdır. # Her ne kadar Hollandalı değilseniz bu yol ilk başta bariz olmayabilir. # Şimdi hiç olmamasından iyidir. # Her ne kadar hiçbir zaman çoğu zaman *şu andan* daha iyi olmasa da. # Uygulamayı açıklamak zorsa, bu kötü bir fikirdir. # Uygulamayı açıklamak kolaysa, iyi bir fikir olabilir.

Hatırlatma: Paskalya yumurtası yorumları tüm kaynak kodlarında hoş karşılanmaz. Bunlardan herhangi birini yapmadan önce lütfen proje veya veri havuzu politikasına veya çalışanınızın el kitabına bakın.

Önemli Noktalar

Bugün, yorumların göründüğünden daha fazlası olduğunu öğrendiniz. Bir zamanlar sonradan akla gelen bu araçlar, artık programlama için paha biçilmez bir iletişim aracı olarak kabul edilmektedir.

• Gelecekteki kod bakımı için bilgilerin belgelenmesine ve korunmasına yardımcı olurlar.
• İyi yorumlar ve kötü yorumlar var.
• Yorumlar otomatik dokümantasyon oluşturmaya yardımcı olabilir.

Şimdi pratik yapma zamanı! Yorumlarda iyi olmanın tek yolu, içeri girip onları eklemektir.

Yorumları programlama düşünce sürecinizin bir parçası haline getirerek, artık gerçekleştirilecek fazladan bir adım haline gelmezler. İşte pratik yapmanın bazı yolları:

• Mevcut projelerinizi belgeleyin ve proje veya veri havuzu için belirlenen standartlara dikkat edin.
• Biçimlendirmenizi ve kurallarınızı kontrol altında tutmak için tüm projelerinizde bir linter kullanın.
• Bir belge oluşturucu bulun ve çalışmanızı yayınlayın.

Yorum ve belgeler konusunda yardıma ihtiyaç duyan açık kaynaklı bir projeyi desteklerken pratik yapabilir ve katkıda bulunabilirsiniz.

Buradan Nereye Gidilir?

Yorum yapma hakkında daha fazla bilgi edinmek istiyorsanız, bu makalelere ve kaynaklara göz atın. Bu makalenin yazılmasında birçoğuna danışıldı.

Umarız yorum yaparken bu bakış hoşunuza gitmiştir! Paylaşmak istediğiniz sorularınız, önerileriniz veya ipuçlarınız mı var? Bu makale için forumda bize katılın. Hepiniz birbirinizden öğrenebilirsiniz.

Yazar Hakkında

Roberto Machorro, 25 yılı aşkın bir süredir profesyonel olarak programlama yapıyor ve bir o kadar uzun süredir kod yorumluyor. Kötü yazılmış bir kodu sürdürmek veya mevcut olmayan belgelerle mücadele etmek zorunda kalmanın verdiği hayal kırıklığından kurum içi, üçüncü taraf ve açık kaynak kodunu belgelemeyi savundu. HeaderDoc, JavaDoc kullanarak kütüphane belgeleriyle çalışmaya başladı ve şimdi DocC'nin keyfini çıkarıyor.

• SEO Destekli İçerik ve Halkla İlişkiler Dağıtımı. Bugün Gücünüzü Artırın.
• PlatoData.Network Dikey Üretken Yapay Zeka. Kendine güç ver. Buradan Erişin.
• PlatoAiStream. Web3 Zekası. Bilgi Genişletildi. Buradan Erişin.
• PlatoESG. Otomotiv / EV'ler, karbon, temiz teknoloji, Enerji, Çevre, Güneş, Atık Yönetimi. Buradan Erişin.
• Blok Ofsetleri. Çevre Dengeleme Sahipliğini Modernleştirme. Buradan Erişin.
• Kaynak: https://www.kodeco.com/38887676-code-comments-how-to-write-clean-and-maintainable-code