코드 주석에서 해야 할 일 5가지와 하지 말아야 할 것 3가지

코드 주석은 코드 자체보다 더 중요하다고 할 수 있습니다. 다음은 코드에 작성하는 주석이 친근한지 확인하는 몇 가지 방법입니다.

독자가 이미 알고 있는 내용을 반복하지 마세요.

코드의 기능을 명확하게 설명하는 주석은 유용하지 않습니다. 우리에게 도움이 되었습니다.

// 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에서 맞춤법을 검사할 수 있습니다. 이 기능이 없다면 플러그인을 다운로드하여 직접 사용해 보세요!

더 많이 연습하세요

연습이 완벽을 만듭니다. 유용한 댓글을 작성해 보고 다른 개발자에게 귀하의 댓글이 유용한지 물어보세요. 시간이 지남에 따라 친절한 댓글이 무엇인지 알게 될 것입니다.

다른 사람의 댓글을 검토하려면

코드를 검토할 때 주석 확인을 무시하는 경우가 많습니다. 더 많은 의견을 묻는 것을 두려워하지 말고 질문을 해야 합니다. 모두가 좋은 메모를 쓰는 좋은 습관을 들이면 세상은 더 나은 곳이 될 것입니다.

요약

댓글은 개발 과정에서 매우 중요한 부분이지만 댓글을 위해 댓글을 달아서는 안 됩니다. 주석은 유용하고 간결해야 하며 코드를 보완해야 합니다. 주석은 코드를 한 줄씩 설명하는 데 사용되어서는 안 되며, 대신 비즈니스 논리, 추론 및 향후 영향을 설명하는 데 사용해야 합니다.