[JS-기초편] 6.주석 달기(comments)

 

 

우리가 작성한 코드는 브라우저를 위한 것으로 보일 수 있습니다.

 

let xPos = -500;

function boringComputerStuff() {
  xPos += 5;

  if (xPos > 1000) {
    xPos = -500;
  }
}
boringComputerStuff();

 

곧 알게 되겠지만 그렇지 않습니다. 

 

우리 코드에 대한 또 다른 청중이 있습니다. 

 

그 청중은 인간으로 구성되어 있습니다.

 

여러분과 제가 다른 자바스크립트 개발자들과 함께 일하는 경우가 있습니다.

 

우리는 종종 남들의 코드를 볼 것이고 남들은 종종 우리의 코드를 볼 것입니다.

 

이 모든 코드를 가능한 한 효율적으로 보이게 하려면 우리가 아닌 다른 사람이 코드를 보고있을 때 코드가 뭘 의미하고 있는지 명확하게 전달해야 합니다.

 

솔로 작업을 하더라도 이 방식은 적용됩니다.

 

오늘 당신에게 의미가있는 그 화려한 기능은 다음 주에 볼 때 횡설수설하게 보일 수 있습니다.

 

이 문제를 해결하는 방법에는 여러 가지가 있습니다.

 

가장 좋은 방법 중 하나는 주석이라는 것을 사용하는 것입니다.

 

이제 주석이 무엇인지, 또 JavaScript에서 주석을 지정하는 방법을 배우고, 주석을 사용하는 방법에 대한 몇 가지 모범 사례를 배웁시다.

 

 

주석은 무엇?

 

주석은 인간에게 무언가를 전달하기 위해 코드의 일부로 작성하는 것입니다.

 

// This is for not inviting me to your birthday party!
let blah = true;

function sweetRevenge() {
  while (blah) {
    // Infinite dialog boxes! HAHAHA!!!!
    alert("Hahahaha!");
  }
}
sweetRevenge();

 

이 예에서 주석은 // 문자로 표시되며 설명중인 코드에 대해 유용한 정보를 제공합니다.

 

주석에 대해 명심해야 할 점은 주석은 실행되지 않는다는 것입니다.

 

JavaScript는 귀하의 의견을 무시합니다. 당신을 좋아하지 않습니다.

 

무슨 말을 해야 하는지 신경 쓰지 않으므로 적절한 구문, 구두점, 철자등에 대해 걱정할 필요가 없습니다.

 

주석은 코드가 수행하는 작업을 이해하는 데 도움이 되는 용도로만 존재합니다.

 

주석이 제공하는 다른 목적이 하나 있습니다. 

 

주석을 사용하여 실행하지 않으려는 코드 줄을 표시 할 수 있습니다.

 

function insecureLogin(input) {
  if (input == "password") {
    //let key = Math.random() * 100000;
    //processLogin(key);
  }
  return false;
}     

 

이 예에서는 코드 편집기에서 다음 두 줄을 볼 수 있지만 실행되지는 않습니다.

 

// let key = Math.random() * 100000;
// processLogin(key);

 

편집기를 메모장 비슷하게 사용하는 경우이며, 주석은 애플리케이션이 실행되는 방식에 영향을 주지 않고 그 코드가 작동하는 방식을 추적하는 좋은 방법입니다.

 

 

 

싱글 라인 주석 (Single Line Comments)

 

코드에 주석을 지정하는 방법에는 여러 가지가 있습니다.

 

한 가지 방법은 // 표시로 한줄 주석을 작성하는 것입니다. 이 한줄 주석은 우리가 이미 여러 번 본 주석입니다.

 

이러한 주석은 전용 라인에 지정할 수 있습니다.

 

// Return the larger of the two arguments
function max(a, b) {
  if (a > b) {
    return a;
  } else {
    return b;
  }
}

 

명령문과 같은 줄에 이러한 주석을 지정할 수도 있습니다.

 

let zorb = "Alien"; // Annoy the planetary citizens

 

우리가 코멘트를 지정하는 곳은 전적으로 프로그래머에 달려 있습니다.

 

작성중인 주석에 적합한 위치를 선택하십시오.

 

우리의 주석(코멘트)은 애플리케이션의 일부로 실행되지 않습니다.

 

 

 

멀티 라인 주석(Multi-Line Comments)

 

한 줄 주석의 문제점은 주석을 달고 자하는 모든 줄 앞에 // 문자를 지정해야한다는 것입니다. 

 

특히 긴 주석을 작성하거나 많은 양의 코드를 주석 처리하는 경우에는 정말 피곤할 수 있습니다.

 

이러한 상황에서는 주석을 지정하는 다른 방법이 있습니다.

 

/* 및 */ 문자를 사용하여 주석의 시작과 끝을 지정합니다.

 

/*
let mouseX = 0;
let mouseY = 0;
 
canvas.addEventListener("mousemove", setMousePosition, false);
 
function setMousePosition(e) {
  mouseX = e.clientX;
  mouseY = e.clientY;
}
*/

 

각 줄 앞에 // 표시를 하는 대신 /* ... */ 문자를 사용하여 많은 시간을 아낄 수 있습니다.

 

대부분의 응용 프로그램에서 문서화하려는 내용에 따라 한 줄 주석과 여러 줄 주석의 조합을 사용합니다.

 

이는 우리가 이 두 가지 주석 방식에 익숙해야 함을 의미합니다.

 

 

주석달기 모범 사례

 

이제 주석이 무엇인지 왜 좋은지 알았으므로, 코드를 쉽게 읽을 수 있도록 주석을 올바르게 사용하는 방법에 대해 조금 이야기 해 보겠습니다.

 

1. 코드를 작성할 때 항상 주석을 달아야합니다. 주석을 작성하는 것은 지루하지만 코드 작성에서 중요한 부분입니다. 지루한 JavaScript 줄을 한 줄씩 읽는 것과 달리 주석을 읽고 코드가 무엇을하는지 이해하는 것이 여러분 (및 다른 사람들)에게 훨씬 더 시간 효율적입니다.

2. 나중을 위해 댓글 작성을 연기하지 마십시오. 나중으로 코멘트 작성을 연기하는 것은 집안일을 미루는 것과 같습니다. 작성하는 동안 코드에 주석을 달지 않으면 나중에 주석 달기를 잊어 버릴 수 있습니다. 그것은 좋은 일이 아닙니다.

3. 더 많은 영어와 더 적은 JavaScript를 사용하십시오. 주석은 JavaScript를 작성할 때 영어 (또는 의사 소통을 선호하는 언어)를 자유롭게 사용할 수있는 몇 안되는 위치 중 하나입니다. 코드로 주석을 불필요하게 복잡하게 만들지 마십시오. 명확하게. 간결해야합니다. 단어를 사용하십시오.

4. 공백을 받아들이십시오. 큰 코드 블록을 스캔 할 때 주석이 눈에 잘 띄고 명확하게 따라야합니다. Spacebar와 Enter를 사용하여 자유로워지기 바랍니다.

5. 명백한 것을 언급하지 마십시오. 코드 줄이 자명한 경우 경고로 표시해야하는 미묘한 동작이 없는 한 코드가 수행하는 작업을 설명하는 데 시간을 낭비하지 마십시오. 대신 코드에서 덜 분명한 부분을 주석 처리하는 데 시간을 투자하십시오.

 

공백과 관련되서 아래를 보십시요.

 

function selectInitialState(state) {
  let selectContent = document.querySelector("#stateList");
  let stateIndex = null;

  /*  
      For the returned state, we would like to ensure that
      we select it in our UI. This means we iterate through
      every state in the drop-down until we find a match. 
      When a match is found, we ensure it gets selected.
  */

  for (let i = 0; i < selectContent.length; i++) {

    let stateInSelect = selectContent.options[i].innerText;

    if (stateInSelect == state) {
      stateIndex = i;
    }
  }

  selectContent.selectedIndex = stateIndex;
}

 

주석은 나머지 코드와 구별 할 수 있도록 적절한 간격으로 배치되어 있습니다.

 

귀하의 의견이 식별하기 어려운 임의의 위치에 흩어져 있으면 불필요하게 읽는 속도가 느려집니다.

 

여기에서 볼 수있는 모범 사례는 올바르게 주석 처리된 코드를 작성하는 데 도움이 될 것입니다.

 

다른 사람들과 함께 더 큰 프로젝트를 진행하고 있다면, 귀하의 팀은 적절한 주석이 어떻게 보이는지에 대한 몇 가지 정해진 지침을 이미 가지고 있다고 확신 할 수 있습니다.

 

이러한 지침을 이해하고 따르십시오. 당신은 만족 할 것입니다.

 

또한 당신의 팀도 만족 할 것입니다.

 

 

 

결론

주석은 종종 필요악으로 간주됩니다.

 

결국, 이미 알고있는 내용을 문서화하는 데 몇 분 정도 시간을 할애 하시겠습니까, 아니면 다음 멋진 기능을 구현 하시겠습니까?

 

코멘트를 설명하는 방법은 다음과 같습니다.

 

장기적인 투자입니다.

 

주석의 가치와 이점은 종종 명확하지 않습니다.

 

다른 사람들이 여러분의 코드를 살펴 보게 할 때 분명해지며, 코드와 작동 방식을 모두 잊어 버린 후 자신의 코드를 다시 봐야 할 때 분명해집니다.

 

단기 시간 절약을 위해 장기적인 시간 절약을 희생하지 마십시오.

 

너무 늦기 전에 한 줄 (//) 및 여러 줄 (/ * ... * /) 주석에 투자하십시오.

 

다음편에는 타이머 함수에 대해 알아보겠습니다.