Можно сказать, что комментарии к коду важнее самого кода. Вот несколько способов сделать комментарии, которые вы пишете в коде, дружелюбными:

Не повторяйте то, что читатели уже знают

Комментарии, которые лишь описывают, что делает код, не помогают нам.

// If the color is red, turn it green 
if (color.is_red()) { 
    color.turn_green(); 
} 

Обязательно комментируйте, чтобы объяснить причины и историю

Если бизнес-логику в коде, возможно, придётся обновить или изменить позже, следует оставить комментарий.

/* The API currently returns an array of items 
even though that will change in an upcoming ticket. 
Therefore, be sure to change the loop style here so that 
we properly iterate over an object */ 
 
var api_result = {items: ["one", "two"]}, 
items = api_result.items, 
num_items = items.length; 
 
for(var x = 0; x < num_items; x++) { 
    ... 
}

Не делайте комментарии в той же строке слишком длинными

Ничто так не раздражает разработчиков, как необходимость тащить горизонтальную полосу прокрутки, чтобы прочитать комментарии. На самом деле большинство разработчиков предпочтут игнорировать такие комментарии, потому что их действительно неудобно читать.

function Person(name) { 
    this.name = name; 
    this.first_name = name.split(" ")[0]; // This is just a shot in the dark here. If we can extract the first name, let's do it 
} 

Размещайте длинные комментарии над логикой, а короткие — после неё

Комментарии можно размещать рядом с кодом, если они не превышают 120 символов. В противном случае следует размещать комментарий непосредственно над оператором.

if (person.age < 21) { 
    person.can_drink = false; // 21 drinking age 
 
    /* Fees are given to those under 25, but only in 
    some states. */ 
    person.has_car_rental_fee = function(state) { 
        if (state === "MI") { 
            return true; 
        } 
    }; 
}

Не добавляйте ненужные комментарии только ради комментариев

Слишком многословные комментарии могут запутать. Возможно, в школе учитель учил вас добавлять комментарии ко всем операторам, чтобы помочь разработчикам лучше понимать. Но это неправильно. Если кто-то говорит такое, вы должны немедленно отвесить ему две большие пощёчины. Код должен оставаться чистым и кратким, в этом нет сомнений. Если ваш код требует построчного объяснения, то больше всего вам нужен рефакторинг.

if (person.age >= 21) { 
    person.can_drink = true; // A person can drink at 21 
    person.can_smoke = true; // A person can smoke at 18 
    person.can_wed = true; // A person can get married at 18 
    person.can_see_all_movies = true; // A person can see all movies at 17 
    //I hate babies and children and all things pure because I comment too much 
}

Пишите комментарии без орфографических ошибок

Не оправдывайте орфографические ошибки в комментариях к коду. IDE может проверить орфографию за вас. Если в ней нет такой функции, скачайте плагин и сделайте это сами!

Обязательно много практикуйтесь

Практика ведёт к совершенству. Попробуйте написать несколько полезных комментариев, и вы можете спросить других разработчиков, полезны ли ваши комментарии. Со временем вы постепенно поймёте, что считается дружелюбными комментариями.

Обязательно просматривайте комментарии других

Во время ревью кода мы часто склонны игнорировать комментарии. Не бойтесь просить больше комментариев; вам следует задавать вопросы. Если каждый выработает полезную привычку писать хорошие комментарии, мир станет лучше.

Итог

Комментарии — очень важная часть процесса разработки, но не стоит комментировать ради комментариев. Комментарии должны быть полезными, краткими и дополнять код. Комментарии не следует использовать для построчного объяснения кода; вместо этого их следует использовать для объяснения бизнес-логики, обоснований и последствий для будущего.