요약
- 문(statement), 주석 및 주석을 포함한 JavaScript 문법의 다양한 측면에 대해 설명해.
- 최소한의 주석이 필요한 명확하고 간결한 코딩가 중요해.
- 주석은 아키텍처, 함수 사용법, 매개변수를 설명하고 문제를 해결하기 위해 특정 방법을 사용한 이유를 설명하는 데 유용해. 또 미묘한 기능을 강조하고 향후 개발을 위한 지침을 제공하는 데에도 유용해.
- 좋은 주석은 코드 가독성을 개선하고 리팩토링 또는 유지 관리 시 시간과 노력을 절약할 수 있어.
자바스크립트 문법
문(statement)은 어떤 작업을 수행하는 문법 구조(syntax structure)와 명령어(command)를 의미해
alert('Hello');
alert('World');같은 문장에 있을 경우 세미 콜론을 추가해줘야해. 그리고 아래와 같은 특수항 상황에서도 세미콜론이 필요해
alert("제대로 동작합니다.");
[1, 2].forEach(alert)주석의 방법
// : 한줄 주석
/**/ : 여러줄 주석
좋지 않은 주석
코드에서 무슨 일이 일어나는지 기재
// 이 코드는 (...)과 (...)을 수행합니다
// A라는 개발자가 이 기능에 대해 알고...
very;
complex;
code;
좋은 코드
그러나 좋은 코드엔 ‘설명이 담긴(explanatory)’ 주석이 많아선 안 되고. 주석 없이 코드 자체만으로 코드가 무슨 일을 하는지 쉽게 이해할 수 있어야 해.
이와 관련된 규칙!.
코드가 불분명해서 주석 작성이 불가피하다면 코드를 다시 작성해야 한다는 의미!
단 실무에선, ‘설명이 담긴’ 주석을 작성하는 게 불가피한 경우도 있어. 알고리즘이 복잡한 코드를 작성하는 경우나 최적화를 위해 코드를 약간 비틀어 작성할 땐 설명을 적어야 해. 이런 경우를 제외하곤 간결하고 코드 자체만으로 설명이 가능하게 코딩여야 해.
좋은 주석
아키텍처를 설명하는 주석
고차원 수준 컴포넌트 개요, 컴포넌트 간 상호작용에 대한 설명, 상황에 따른 제어 흐름 등은 주석에 넣는 게 좋아.
함수 용례와 매개변수 정보를 담고 있는 주석
JSDoc이라는 특별한 문법을 사용하면 함수에 관한 문서를 쉽게 작성할 수 있어. 여기엔 함수 용례, 매개변수, 반환 값 정보가 들어가.
예시:
/**
* x를 n번 곱한 수를 반환함
*
* @param {number} x 거듭제곱할 숫자
* @param {number} n 곱할 횟수, 반드시 자연수여야 함
* @return {number} x의 n 거듭제곱을 반환함
*/
function pow(x, n) {
...
}이렇게 주석을 달면 코드를 읽어보지 않고도 함수의 목적과 사용법을 한눈에 알 수 있어.
WebStorm 등의 다양한 에디터는 이런 주석을 이용해 자동 완성 기능, 자동 에러 검출 기능 등을 제공.
JSDoc 3이나 기타 유사한 툴을 사용하면 주석으로 HTML 문서를 만들 수 있음. 자세한 정보는 http://usejsdoc.org/에서 확인.
왜 이런 방법으로 문제를 해결했는지를 설명하는 주석
- 무엇이 적혀있는지는 중요해 근데 무슨 일이 일어나고 있는지 파악하려면, 무엇이 적혀있지 않은 지가 더 중요할 수 있어.
"왜 이 문제를 이런 방법으로 해결했나?"라는 질문에 코드는 답을 해 줄 수 없기 때문이야.
문제 해결 방법이 여러 가지인데 왜 하필이면 이 방법을 택했는지 (선택한 방법이 가장 나은 것이 아니어도) 의문이 들 때가 있어.
- 왜 이런 방법을 써서 문제를 해결했는지 알려주는 주석이 없으면 다음과 같은 일이 발생할 수 있거든.
내가(혹은 동료)가 코드를 작성한 후 시간이 꽤 흘러서 다시 열어본다. 근데 그 코드가 별로야.
"그때는 내가 멍청했구나. 하지만 지금은 더 똑똑해"라고 생각하고, 이전보단 ‘더 명확하고 올바른’ 방법으로 코드를 개선하려 할거야!.
코드를 개선하려는 시도까지는 좋아. 근데 리팩토링 과정에서 '더 명확’하다고 생각했던 방법을 적용하면 문제가 발생해.
이미 시도해봤던 방법이기 때문에 왜 이 방법이 먹히지 않는지 희미하게 기억이 떠오르거든. 새로 작성한 코드를 되돌렸지만, 시간이 낭비했어!
해결 방법을 담고 있는 주석은 아주 중요한 역할을 해. 이전에 했던 실수를 방지하는 안내판 역할을 하기 때문이야.
미묘한 기능이 있고, 이 기능이 어디에 쓰이는지를 설명하는 주석
마지막으로 직감에 반하는 미묘한 동작을 수행하는 코드가 있다면 주석을 달아주는 게 좋아
참고
