코드 구조 장에서 알 수 있듯이 주석은 // 로 시작하는 한 줄일 수 있고 /* ... */ 여러 줄일 수 있습니다.
우리는 일반적으로 코드가 작동하는 방법과 이유를 설명하기 위해 이를 사용합니다.
언뜻 보면 주석 달기가 당연할 수도 있지만, 프로그래밍 초보자들은 주석을 잘못 사용하는 경우가 많습니다.
초보자는 "코드에서 무슨 일이 일어나고 있는지" 설명하기 위해 주석을 사용하는 경향이 있습니다. 이와 같이:
// 이 코드는 이 일(...)과 저 일(...)을 수행합니다. // ...그리고 또 누가 알겠어요... 매우; 복잡한; 암호;
그러나 좋은 코드에서는 그러한 "설명" 주석의 양이 최소화되어야 합니다. 진지하게, 코드는 그것들 없이도 이해하기 쉬워야 합니다.
이에 대한 훌륭한 규칙이 있습니다. "코드가 너무 명확하지 않아 주석이 필요할 경우 대신 다시 작성해야 할 수도 있습니다."
때로는 다음과 같이 코드 조각을 함수로 바꾸는 것이 도움이 될 수 있습니다.
함수 showPrimes(n) {
다음프라임:
for (let i = 2; i < n; i++) {
// i가 소수인지 확인
for (let j = 2; j < i; j++) {
if (i % j == 0) 계속 nextPrime;
}
경고(i);
}
} isPrime 함수를 분해한 더 나은 변형은 다음과 같습니다.
함수 showPrimes(n) {
for (let i = 2; i < n; i++) {
if (!isPrime(i)) 계속;
경고(i);
}
}
함수 isPrime(n) {
for (let i = 2; i < n; i++) {
if (n % i == 0) false를 반환합니다.
}
사실을 반환;
}이제 코드를 쉽게 이해할 수 있습니다. 함수 자체가 주석이 됩니다. 이러한 코드를 자기 설명적이 라고 합니다.
그리고 다음과 같이 긴 "코드 시트"가 있는 경우:
// 여기에 위스키를 추가합니다.
for(let i = 0; i < 10; i++) {
drop = getWhisky();
냄새(드롭);
추가(드롭, 유리);
}
// 여기에 주스를 추가합니다.
for(let t = 0; t < 3; t++) {
let 토마토 = getTomato();
검사하다(토마토);
주스 = 프레스(토마토);
add(주스, 유리);
}
// ...그러면 다음과 같은 기능으로 리팩터링하는 것이 더 나은 변형일 수 있습니다.
add위스키(유리);
addJuice(유리);
함수 addWhiskey(컨테이너) {
for(let i = 0; i < 10; i++) {
drop = getWhisky();
//...
}
}
함수 addJuice(컨테이너) {
for(let t = 0; t < 3; t++) {
let 토마토 = getTomato();
//...
}
}다시 한번, 함수 자체가 무슨 일이 일어나고 있는지 알려줍니다. 코멘트할 내용이 없습니다. 또한 분할하면 코드 구조가 더 좋습니다. 모든 함수가 수행하는 작업, 수행되는 작업, 반환하는 작업이 명확합니다.
실제로는 "설명적인" 코멘트를 완전히 피할 수는 없습니다. 복잡한 알고리즘이 있습니다. 그리고 최적화를 위한 현명한 "조정"이 있습니다. 그러나 일반적으로 우리는 코드를 단순하고 자기 설명적으로 유지하려고 노력해야 합니다.
따라서 설명적인 코멘트는 일반적으로 좋지 않습니다. 어떤 댓글이 좋은가요?
아키텍처 설명
구성 요소에 대한 높은 수준의 개요, 상호 작용 방식, 다양한 상황에서의 제어 흐름 등을 제공합니다. 즉, 코드에 대한 조감도입니다. 코드를 설명하는 고급 아키텍처 다이어그램을 구축하는 특수 언어 UML이 있습니다. 확실히 공부할 가치가 있습니다.
문서 기능 매개변수 및 사용법
함수를 문서화하는 JSDoc 특수 구문(사용법, 매개변수, 반환 값)이 있습니다.
예를 들어:
/**
* x의 n승을 반환합니다.
*
* @param {number} x 올릴 숫자입니다.
* @param {number} n 거듭제곱은 자연수여야 합니다.
* @return {number} x의 n제곱입니다.
*/
함수 pow(x, n) {
...
}이러한 주석을 사용하면 함수의 목적을 이해하고 코드를 살펴보지 않고도 함수를 올바른 방식으로 사용할 수 있습니다.
그런데 WebStorm과 같은 많은 편집자들도 이를 이해하고 이를 사용하여 자동 완성 및 일부 자동 코드 검사를 제공할 수 있습니다.
또한 주석에서 HTML 문서를 생성할 수 있는 JSDoc 3과 같은 도구가 있습니다. JSDoc에 대한 자세한 내용은 https://jsdoc.app에서 확인할 수 있습니다.
왜 이런 식으로 작업이 해결됩니까?
쓰여진 내용이 중요합니다. 그러나 쓰여지지 않은 내용이 무슨 일이 일어나고 있는지 이해하는 데 훨씬 더 중요할 수 있습니다. 작업이 정확히 이런 방식으로 해결되는 이유는 무엇입니까? 코드는 대답을 제공하지 않습니다.
문제를 해결하는 방법이 여러 가지라면 왜 이 방법인가요? 특히 그것이 가장 명백하지 않은 경우에는 더욱 그렇습니다.
그러한 의견이 없으면 다음과 같은 상황이 가능합니다.
귀하(또는 귀하의 동료)가 얼마 전에 작성된 코드를 열고 그것이 "최적화되지 않음"을 확인합니다.
당신은 "그때 내가 얼마나 어리석었는지, 그리고 지금은 얼마나 더 똑똑해졌는지"라고 생각하고 "더 명확하고 정확한" 변형을 사용하여 다시 작성합니다.
...다시 쓰고 싶은 충동은 좋았습니다. 그러나 그 과정에서 실제로는 "더 확실한" 해결책이 부족하다는 것을 알게 됩니다. 당신은 이미 오래 전에 그것을 시도했기 때문에 그 이유를 어렴풋이 기억합니다. 올바른 변형으로 되돌렸지만 시간이 낭비되었습니다.
해결 방법을 설명하는 의견은 매우 중요합니다. 이는 올바른 방식으로 개발을 계속하는 데 도움이 됩니다.
코드에 미묘한 기능이 있습니까? 어디에 사용되나요?
코드에 미묘하고 반직관적인 부분이 있다면 분명히 언급할 가치가 있습니다.
좋은 개발자의 중요한 표시는 댓글입니다. 즉, 댓글의 존재 여부도 마찬가지입니다.
좋은 댓글을 통해 우리는 코드를 잘 유지할 수 있고, 나중에 다시 돌아와서 더 효과적으로 사용할 수 있습니다.
댓글을 달아주세요:
전반적인 아키텍처, 높은 수준의 보기입니다.
기능 사용법.
특히 즉각적으로 명확하지 않은 경우 중요한 솔루션입니다.
댓글을 피하세요:
이는 "코드가 어떻게 작동하는지"와 "무엇을 하는지"를 알려줍니다.
코드를 너무 간단하고 자체적으로 설명할 수 있어서 필요하지 않은 경우에만 입력하세요.
주석은 JSDoc3과 같은 자동 문서화 도구에도 사용됩니다. 주석은 주석을 읽고 HTML 문서(또는 다른 형식의 문서)를 생성합니다.