کامنت گذاری در CleanCode (قسمت آخر)

• خودداری از نشانگرهای موقعیتی-Avoid positional markers
• کامنت ها را در خارج از کد اصلی قرار ندهید-Don't leave commented out code in your codebase
• کامنت ژورنالی نداشته باشید-Don't have journal comments
• فقط چیزهایی را کامنت کنید که پیچیدگی منطق تجاری دارند-Only comment things that have business logic complexity

خودداری از نشانگرهای موقعیتی Avoid positional markers

آنها معمولاً فقط سر و صدا می کنند.بگذارید توابع و نام های متغیر به همراه تورفتگی و قالب بندی مناسب ، ساختار بصری را به کد شما بدهند.

Bad:

////////////////////////////////////////////////////////////////////////////////
// Scope Model Instantiation
////////////////////////////////////////////////////////////////////////////////
var model = new[]
{
    menu: 'foo',
    nav: 'bar'
};

////////////////////////////////////////////////////////////////////////////////
// Action setup
////////////////////////////////////////////////////////////////////////////////
void Actions()
{
    // ...
};

Bad:

#region Scope Model Instantiation

var model = {
    menu: 'foo',
    nav: 'bar'
};

#endregion

#region Action setup

void Actions() {
    // ...
};

#endregion

Good:

var model = new[]
{
    menu: 'foo',
    nav: 'bar'
};

void Actions()
{
    // ...
};

کامنت ها را در خارج از کد اصلی قرار ندهید Don't leave commented out code in your codebase

کنترل نسخه(Version control) به یک دلیل وجود دارد.کد قدیمی را در history بگذارید.

Bad:

doStuff();
// doOtherStuff();
// doSomeMoreStuff();
// doSoMuchStuff();

Good:

doStuff();

کامنت ژورنالی نداشته باشید Don't have journal comments

به یاد داشته باشید ، از کنترل نسخه استفاده کنید! دیگر نیازی به کدهای مرده ، کد comment شده و به خصوص comment های ژورنالی نیست.برای دریافت تاریخچه از log git استفاده کنید!

Bad:

/**
 * 2018-12-20: Removed monads, didn't understand them (RM)
 * 2017-10-01: Improved using special monads (JP)
 * 2016-02-03: Removed type-checking (LI)
 * 2015-03-14: Added combine with type-checking (JR)
 */
public int Combine(int a,int b)
{
    return a + b;
}

Good:

public int Combine(int a,int b)
{
    return a + b;
}

فقط چیزهایی را کامنت کنید که پیچیدگی منطق تجاری دارند Only comment things that have business logic complexity

نظرات عذرخواهی است ، نه یک الزام.کد خوب اغلب خود را مستند می کند.

Bad:

public int HashIt(string data)
{
    // The hash
    var hash = 0;

    // Length of string
    var length = data.length;

    // Loop through every character in data
    for (var i = 0; i < length; i++)
    {
        // Get character code.
        const char = data.charCodeAt(i);
        // Make the hash
        hash = ((hash << 5) - hash) + char;
        // Convert to 32-bit integer
        hash &= hash;
    }
}

Better but still Bad:

public int HashIt(string data)
{
    var hash = 0;
    var length = data.length;
    for (var i = 0; i < length; i++)
    {
        const char = data.charCodeAt(i);
        hash = ((hash << 5) - hash) + char;

        // Convert to 32-bit integer
        hash &= hash;
    }
}

اگر یک comment توضیح داد که کد درحال انجام چیست ،احتمالاً این یک comment بی فایده است و می تواند با یک نام متغیر یا تابعی که به خوبی شناخته شده باشد ، پیاده سازی شود.comment در کد قبلی می تواند با تابعی به نام ConvertTo32bitInt جایگزین شود ، بنابراین این comment هنوز بی فایده است.با این وجود دشوار است که با کدی بیان کنید چرا توسعه دهنده الگوریتم هش djb2 را به جای sha-1 یا یک تابع هش دیگر انتخاب می کند.در این صورت یک comment قابل قبول است.

Good:

public int Hash(string data)
{
    var hash = 0;
    var length = data.length;

    for (var i = 0; i < length; i++)
    {
        var character = data[i];
        // use of djb2 hash algorithm as it has a good compromise
        // between speed and low collision with a very simple implementation
        hash = ((hash << 5) - hash) + character;

        hash = ConvertTo32BitInt(hash);
    }
    return hash;
}

private int ConvertTo32BitInt(int value)
{
    return value & value;
}

برای مشاهده ابزار های visual studio برای نوشتن کد تمیز و همچنین خواند همین مطالب برای زبان های دیگر به منبع این بخش مراجعه کنید.