주석을 어떻게 다는게 좋을까...

💬 협업과 공부를 위한 "주석 잘 다는 법" 가이드

코드를 작성할 때 주석은 단순한 메모 그 이상입니다. 협업에서는 의사소통 도구이고, 개인 공부에서는 나중의 나를 위한 설명서입니다. 이번 글에서는 협업과 개인 공부 각각의 상황에 맞춘 주석 작성법과 실제 예시를 소개하겠습니다.

---

✍️ 주석의 기본 원칙

✅ 1. 왜를 설명하라

• 무엇을 설명하기보다는 왜 그렇게 했는지를 중심으로 작성합니다.
• 예) // 성능을 위해 이중 루프 대신 해시 맵 사용

✅ 2. 코드와 멀어지지 않게

• 주석은 바로 위나 옆에 위치해야 이해가 쉽습니다.
• 예외적으로 블록 주석은 함수/클래스 상단에 위치합니다.

✅ 3. 과하지도, 부족하지도 않게

• 당연한 내용을 반복하지 않습니다.
• 필요 이상의 설명은 오히려 가독성을 해칩니다.

---

🤝 협업을 위한 주석 작성법

협업에서는 "다른 개발자"를 고려해야 합니다. 그 사람이 내 코드의 맥락을 이해할 수 있도록 의도, 주의사항, 예외 처리 이유를 명확히 기록해야 합니다.

📌 협업 시 유용한 주석 패턴

1. 의도 설명

// 새로고침 시 로그인 유지 위해 토큰을 localStorage에서 불러옵니다
const token = localStorage.getItem('token');

2. 예외 처리 이유

// 사용자가 파일을 선택하지 않고 종료할 수도 있으므로 null 체크
if (selectedFile == null) {
    return;
}

3. TODO / FIXME 주석 활용

// TODO: API 응답 예외처리 로직 추가 예정

// FIXME: 페이지네이션이 누락됨 – 추후 구현 필요

4. 변경 히스토리 (간단히)

/*
[2025-05-24 담당자이름]
리스트에서 중복 제거 로직 변경 – 성능 개선 목적
*/

---

 

🧠 개인 공부용 주석 작성법

개인 학습에서는 내가 이해한 개념, 코드 흐름, 외운 문법을 주석으로 정리하면 복습할 때 큰 도움이 됩니다.

📌 개인 공부에 유용한 주석 패턴

1. 용어/개념 정리

# 클로저(closure): 내부 함수가 외부 함수의 지역 변수에 접근할 수 있는 구조

2. 흐름 설명

// Step 1. 사용자 입력 검증
// Step 2. 서버에 요청 전송
// Step 3. 응답 결과 처리

3. 문법/패턴 암기

// initState는 위젯이 처음 생성될 때 한 번만 호출됨
@override
void initState() {
  super.initState();
}

4. 실험용 코드 표시

// 실험: 배열 복사를 포인터로 처리해보기

---

 

💡 팁

팁	설명
🔄 주기적으로 갱신	코드가 바뀌면 주석도 함께 업데이트해야 함
🎯 일관된 스타일 유지	팀 컨벤션에 따라 주석 스타일 통일 (//, /* */, ///, #)
🧹 불필요한 주석 제거	의미 없는 주석은 삭제해서 코드 청결 유지

🧪 주석 안 써도 되는 경우는?

• 너무 단순한 코드 (예: int i = 0;)
• 라이브러리나 프레임워크에서 자주 쓰는 전형적인 코드 (React useState, Flutter build)
• 테스트용 임시 코드 (단, 협업 중이라면 명시적으로 // 테스트용이라고 써야 함)

---

 

💬 언어 및 환경별 주석 기호 정리표

언어 / 환경	한 줄 주석	여러 줄 주석	기타 주석 (문서화 등)
C / C++	//	/* ... */	///, /** ... */ (Doxygen)
Java	//	/* ... */	/** ... */ (JavaDoc)
Python	#	없음 ('''는 문자열 처리)	"""Docstring""" (함수/클래스 문서화)
JavaScript	//	/* ... */	/** ... */ (JSDoc)
TypeScript	//	/* ... */	/** ... */ (TSDoc)
Dart	//	/* ... */	///, /** ... */ (DartDoc)
Swift	//	/* ... */	///, /** ... */ (SwiftDoc)
Kotlin	//	/* ... */	/** ... */ (KDoc)
Go	//	/* ... */ (가능하나 권장 X)	// + 바로 아래에 함수 위치 (GoDoc)
Rust	//	/* ... */	///, //!, /** ... */, /*! ... */
SQL	--	/* ... */	없음
HTML	없음	<!-- ... -->	없음
CSS	없음	/* ... */	없음
Shell (bash, zsh)	#	없음	없음
Windows CMD	REM 또는 ::	없음	없음
PowerShell	#	<# ... #>	없음

 

환경	특징
Shell	# 이후 내용은 모두 주석 처리됩니다. 스크립트 파일 .sh에서도 동일하게 사용됩니다.
CMD (Windows 명령 프롬프트)	REM 또는 ::를 사용합니다. ::는 조건문 안에서는 오류 발생 가능성이 있어 REM을 권장합니다.
PowerShell	#는 한 줄 주석, <# ... #>는 여러 줄 주석에 사용됩니다.