Yorumlama / Kod İçi Belge Stilleri

Bu aptalca bir soru olabilir, ama bir süredir kafamın arkasındaydı ve başka hiçbir yerde iyi bir cevap bulamıyorum.

Sadece bir tane olsa bile her parametreyi bir açıklama ile açıkça listelememiz gerektiğini söyleyen bir öğretmenim var. Bu bir çok tekrarlamaya yol açar:

double MyFunction(const int MyParam);
// Function: MyFunction
// Summary: Does stuff with MyParam.
// Input: int MyParam - The number to do stuff with.
// Output: MyParam with stuff done to it.

Kod içi belgeler yazarken ne kadar ayrıntılısınız?

Yeni başlayanlar için, örneğinizdeki "İşlev:" satırının artık gereksiz olduğunu kabul ediyorum. İnsanların okulda bu tür bir yorum eklemeyi öğrettikleri tecrübem de bu tür yorumları kendi üretim kodlarına eklemeye devam ediyor.

İyi yorumlar kodda ne olduğunu tekrarlamaz. "Neden?" "Ne?" veya nasıl?" Girdilerle ilgili beklentilerin yanı sıra, kodun belirli koşullar altında nasıl davranacağını da kapsarlar. Neden algoritma Y yerine X algoritmasının seçildiğini ele alırlar. Kısacası, tam olarak bir başkası için ¹ kodunu okumaktan alıkoyan şeyler .

^{1: Kodun yazıldığı dili bilen başka biri. Öğretmek için yorum yazmayın, ek bilgi için yorum yazmayın.}

Birçok dilde Ruby, Java, C # ve C ++ gibi API belge oluşturma özellikleri bulunur (bir komut satırı aracıyla). Bu şekilde düşündüğünüzde, API belgelerini yazmayı çok daha önemli hale getirir. Sonuçta, "nasıl yaparım ...?" Bu nedenle Function: MyFunction, fonksiyonun adı herkesin görmesi için açık olduğu gibi tekrarlayan bir şey yapmayacağım . API doküman oluşturma araçları bunu benim için yapacak kadar akıllı. Bununla birlikte, aşağıdaki ayrıntılar, özellikle genel yöntemler / işlevler için yararlıdır:

• Özet (ne işe yarar ve ne zaman alakalı olduğu, nasıl kullanılacağına dair bir özet)
• Parametrelerin listesi ve ne bekleniyor
• Dönüş değeri (çıktı) ne olacak
• Açıkça atılabilecek istisnalar ve nedenleri

Kod hatalarını ayıklamaya çalışırken bunlar yararlı referans araçları haline gelebilir. Çoğu IDE, işlev adının üzerine geldiğinizde araç ipuçlarında API belgelerini de kullanır.

Bu özelliklere sahip olmayan bir dilse, yorumlar yardımcı olur, ancak neredeyse o kadar da değil.

Herkese açık bir API yöntemi ise, evet, özellikle parametreler ve beklenen davranış hakkında ayrıntılı belgeler sağlamalısınız. Birçok kişi bunun özel yöntemler / fonksiyonlar için rahatlayabileceğini düşünüyor, YMMV.

Genel olarak temiz kod (bir şey ve bir şey iyi yapan küçük yöntemler / fonksiyonlar) mantıklı değişken isimleri ile yazmayı tercih ederim. Bu, kodunuzun çoğunu kendi kendine belgelendirir. Bununla birlikte, kesinlikle her zaman uç durumları, eşzamanlılık kullanımını ve karmaşık algoritmaları kullanırım.

Kısacası kendinizi 3 aydan itibaren sabah 3'te 3 aydan itibaren giymek için biraz daha kötü olarak düşünün. Hangi parametrenin (boolean flag) ne anlama geldiğini anlamanın aksine harika kamu dokümanlarınız için kendinize teşekkür edeceksiniz ...

Bu, çoğu -Doc çerçevesinin kod içi belgeleri (JavaDoc, PHPDoc, vb.) Ayrıştırma şekline benzer.

Java'dan IDE tarafından otomatik olarak oluşturulur:

/**
 * [Description]
 * @param str [Description]
 * @param isCondition [Description]
 * @return [Description]
 */
public int testFunction(String str, boolean isCondition) {
    ...
}

Bu, yerleşik dil özellikleri için Dokümanları oluşturmak için kullanılan formatın aynısıdır - Örnek: http://download.oracle.com/javase/6/docs/api/java/lang/String.html

Bu biçim oldukça yararlıdır, çünkü herhangi bir üçüncü taraf kullanıcıya kodunuzla nasıl arayüz kuracağınızı açıkça gösterir. Eğer işlevleriniz sadece dahili olarak kullanılan özel yöntemler ise, o zaman biraz anlamsız olabilir - ama sanırım öğretmeniniz bu ayrımı yapma konusunda deneyimli olana kadar sizi iyi bir uygulamaya sokmaya çalışıyor.

Sık sık biraz gereksiz bulduğum tek bit dönüş açıklamasıdır - Genellikle yöntem açıklamamla hemen hemen aynıdır.

Yorumlar için iki amaç vardır:

1. Aylar / yıllar sonra kodunuza geri döndüğünüzde size kodunuzun ne yaptığını hızlı bir şekilde hatırlatırlar. Bu şekilde, belleğinizi yenilemek için kodunuzu yeniden okumak ve analiz etmek zorunda kalmazsınız.
2. Kodunuzu okuyor veya kodunuzla birlikte çalışarak başkalarının kodunu yapıyor.

Elbette buna yaklaşmanın birçok farklı yolu var ama ne kadar ayrıntılı ve tutarlı olursanız o kadar iyi olursunuz. Etkili yorumlama, etkili programlamanın yaptığı gibi öğrenilmesi zaman alır. Unutmayın, üzerinde çalıştığınız hiçbir şey onu gerçekten garanti edecek kadar büyüktür, ancak okuldaki yorumların görülmesinin zor olduğunu, ancak sadece size tanıtmaya çalıştıklarını unutmayın. Ve genellikle bunu size öğretmenin yolu, profesörünüzün tarzıdır, hiçbir şekilde standart değildir. Sizin için uygun olanı geliştirin. Ve unutmayın ... aptalca bir yorum var! :) Misal:

a += 1; //adds 1 to the value in a

Gerçekten mi? Teşekkürler! LOL

Ben inline yorum ve PHPDoc sözdizimi kullanarak benzer bir şey kullanmak için PHP web sitesinden belgeleri gibi. Aşağıdaki örneğe bakın.

/*
* Finds all the locations where you have access to for this client and returns them in an array .
* @author Radu
* @version 1.0
* @param int $id ( The id of the client for which you're requesting access. )
* @param object $db ( A resource of type Mysql, representing a connection to mysql database, if not supplied the function will connect itself. )
* @return array ( Returns array with id's of locations that you are allowed to see, an empty array if you do not have acces to any locations or returns FALSE and triggers a Warning if any error occuread )
* @use array allowed_locations ( $id [, $db] )
*/
function allowed_locations($id, $db=NULL){ ... }

@Larry Coleman'ın dediği gibi, satır içi yorumlar neden bir parça kod yaptığınızı söylemelidir.

$funcResult = SomeFunction();
if(is_array($funcResult))
{    //Beacause SomeFunction() could return NULL, and count(NULL) = 1
    $c = count($funcResult);
} else {
    $c = 0;
}
if($c == 1)
{
 ... 
}else
{
 ...
}

Doc kuşağının hizmetindeyse, ayrıntılı yorumlar (rahatsız edici olsa da) muhtemelen iyi bir şeydir. Her ne kadar yorumların üstünde kalmak ve güncel tutmak için bir takım hedefi yapmak zorunda.

Sadece yorum tarzı ise onunla sorun olurdu. Aşırı yorumlar, kod kadar yardım edebilir. Kodda eski ve sonuçta yanıltıcı olarak yorumlarda karşılaştığım zaman sayısını sayamıyorum. Genellikle şimdi yorumları görmezden gelir ve ne yaptığını ve neyin ne olduğunu anlamak için kodu ve kodun testlerini okumaya odaklanıyorum.

Açık özlü yorum yapılmamış kodu olmasını tercih ederim . Açıklayıcı iddialar veya yöntemler ile bana bazı testler verin ve mutluyum ve bilgiliyim.