4장 주석
좋은 주석을 소개하는 장. 그리고 좋은 주석은 삭제된 주석뿐, 주석은 적을수록 좋다.
주석은 컴파일되지 않는 코드이다. 단지 프로그래머에게 유의미한 정보를 제공해주기 위해 존재하는데, 그렇지 않은 경우 프로그래밍 코드에 더해 주석을 읽고 해석하는 시간까지 소요되므로 코드 가독성을 해친다고 할 수 있다. 책에서는 주석이 자주 거짓말을 한다고 말한다. 코드가 오래될수록 주석까지 유지보수하기 어려워지고 결국 본 코드에서 멀어지게 되기 때문이다. 좋은 주석이란 꼭 주석을 통해서만 전달할 수 있는 정보를 최소한으로 기재한 주석이라고 할 수 있겠다.
1. 좋은 주석의 예시
- 법적 정보 제공 주석
- 의도와 의미를 명료히 하는 주석
- 결과를 경고하는 주석
- TODO 주석
- 중요성을 강조하는 주석
- 공개 API에서 JSDOCS
// 법적 정보 제공 주석
Copyright (C) 2023, 2024 by Object Mentor, Inc. All rights reserved.
GNU General Public License 버전 2 이상을 따르는 조건으로 배포한다.
// 결과를 경고하는 주석
여유 시간이 충분하지 않다면 실행하지 마십시오.
// 중요성을 강조하는 주석
let listItemContent = match[0].trim(); // 여기서 trim은 정말 중요하다. 문자열에 시작 공백이 있으면 다른 문자열로 인식되기 때문이다.
let listItem = new ListItem(this, listItemContent);
2. 나쁜 주석의 예시
나쁜 주석의 예시들로 직접 코드를 작성해보았다. 아래 코드의 주석들은 모두 삭제 대상이다. (내가 싫어하던 온갖 주절거림을 다 적어보았다. 이것도 나름 어렵다!😂)
// ========== 클래스 구현 ==========
/**
* 숫자 야구 게임을 구현합니다.
* @author Wavy
* @version 13 March 2024
*
* @param {string} secretNumber 맞춰야 하는 목표 값
* @param {number} attempts 시도 횟수
* @param {number} maxAttempts 최대 시도 횟수
*
* 변경 이력 (11-Mar-2024)
* ---------------------
* 2023-12-20: 게임 룰 변경으로 코드 수정함 (S)
* 2023-10-01: 플레이 경험을 향상을 위해 로직 개선 (W)
* 2023-02-03: 사용자 입력값의 유효성 강화를 위해 타입 체크 추가 (S)
*/
class NumberBaseballGame {
secretNumber: string;
attempts: number;
maxAttempts: number;
constructor() {
this.secretNumber = this.generateSecretNumber();
this.attempts = 0;
this.maxAttempts = 10;
}
generateSecretNumber(): string {
// 중복되지 않는 4자리의 숫자 생성
let secretNumber = '';
while (secretNumber.length < 4) {
const digit = Math.floor(Math.random() * 10).toString();
if (!secretNumber.includes(digit)) {
secretNumber += digit;
}
}
return secretNumber;
}
/**
* @param userGuess 사용자가 입력한 숫자 문자열
* 용어 설명
* balls: userGuess 중 자리는 틀리고 숫자는 맞은 것
* strikes: userGuess 중 자리와 숫자가 모두 맞은 것
* @returns {string} 정답 여부 및 결과 문자열
*/
checkGuess(userGuess: string): string {
if (userGuess.length !== 4 || !/^\d+$/.test(userGuess)) {
return '올바른 형식의 4자리 숫자를 입력해주세요.';
}
let balls = 0; // userGuess 중 자리는 틀리고 숫자는 맞은 것
let strikes = 0; // userGuess 중 자리와 숫자가 모두 맞은 것
for (let i = 0; i < userGuess.length; i++) {
const digit = userGuess[i];
if (this.secretNumber.includes(digit)) {
if (this.secretNumber[i] === digit) {
strikes++;
} else {
balls++;
}
}
}
this.attempts++;
// 정답 여부 및 결과 문자열 반환
if (strikes === 4) {
return `축하합니다! ${this.secretNumber}을(를) ${this.attempts}번 만에 맞히셨습니다.`;
} else {
return `${strikes} 스트라이크, ${balls} 볼입니다. 다시 시도해보세요.`;
}
}
// 여기 너무 어렵다...! 헥헥
async play(userGuess: string): Promise<string> {
return new Promise<string>((resolve, reject) => {
setTimeout(() => {
try {
if (this.attempts >= this.maxAttempts) {
resolve('게임 오버! 정답은 ' + this.secretNumber + '입니다.');
} else {
const result = this.checkGuess(userGuess);
resolve(result);
}
} catch (error) {
reject('오류가 발생했습니다: ' + error);
}
}, 5000); // 5초 후에 결과를 출력
});
}
}
// 클래스 구현 END
// ========== 게임 인스턴스 생성 ==========
const game = new NumberBaseballGame();
// 인스턴스 생성 END
// ========== 테스트 코드 ==========
async function testNumberBaseballGame(userInput: string): Promise<void> {
try {
// 정상
const game = new NumberBaseballGame();
console.log('숫자야구 게임을 시작합니다!');
const result = await game.play(userInput);
console.log(result);
} catch (error) {
// 에러
console.error('오류가 발생했습니다:', error);
}
}
// 테스트 코드 END
추가로 정보 전달 목적이 아닌 취소선 의미의 주석이 있다. 필요없는 코드는 바로 삭제해야 한다. 주석으로 처리된 코드는 다른 사람이 어떤 이유로 남겨놓은 것인지 파악 수 없어 지우기도 어렵다. 이런 코드들은 퇴적물처럼 프로젝트에 쌓이고 나중에는 손대기 어려워진다. 앞으로의 팀 프로젝트에서는 코드 포맷을 합의할 때 코드 주석을 남기지 않는 것까지 약속을 하는 게 좋겠다는 걸 배운다.
댓글