[코딩공부] ✅ 잘 쓰는 주석 가이드라인

 

✅ 잘 쓰는 주석 가이드라인

1. 🎯 의도를 설명하라 (What보다 Why)

• 무엇을 하는지는 코드로도 알 수 있지만, 왜 그렇게 했는지는 주석으로만 알 수 있는 경우가 많습니다.

// 시간 초과를 방지하기 위해 타임아웃을 5초로 설정
client.ReceiveTimeout = 5000;

❌ 나쁜 예: client.ReceiveTimeout = 5000; // 타임아웃을 5000으로 설정 (이미 코드에 있음)

---

2. 📌 불명확하거나 복잡한 로직은 꼭 주석 처리

• 조건문, 수학 계산, 트릭 등 복잡한 로직에는 반드시 설명을 달아야 합니다.

// 윤년 계산: 4의 배수이면서 100의 배수가 아니거나, 400의 배수
bool isLeap = (year % 4 == 0 && year % 100 != 0) || year % 400 == 0;

---

3. 📦 구조 단위(클래스/함수/모듈)에는 요약 설명

• 각 함수나 클래스가 무슨 역할을 하는지 상단에 요약 주석 작성

/// <summary>
/// 클라이언트 연결 요청을 수락하고 처리하는 서버 루프
/// </summary>
private void RunServer()
{
    ...
}

---

4. ✂️ 당연한 내용을 반복하지 마라

• 너무 명확한 코드에 설명을 붙이면 노이즈만 생깁니다.

int count = 0; // 변수 count를 0으로 초기화 ← ❌ 불필요

---

5. 🔄 코드 수정 시 주석도 함께 수정

• 주석이 코드와 불일치하면 오히려 해로움

// 포트 8080 사용
int port = 9090;  // ← ❌ 모순

---

6. 🧼 한글 주석은 되도록 짧고 명확하게

• 너무 긴 문장보다, 짧고 핵심적인 단어/문장으로

// 데이터 저장 실패 시 재시도
RetrySave();

---

7. 🧪 TODO / FIXME / NOTE 태그 활용

• 개발 중이거나 주의할 부분을 표시할 때 사용

// TODO: 멀티스레드 환경에서 안전하게 동작하도록 수정 필요
// FIXME: 가끔 null reference 에러 발생함

---

8. 🌐 문서화 주석(XML, Javadoc 등)도 고려

• C#, Java 등에서는 자동 문서화를 위한 주석을 활용 가능

/// <summary>
/// 사용자 로그인 처리를 수행합니다.
/// </summary>
/// <param name="username">사용자 이름</param>
/// <param name="password">비밀번호</param>
public bool Login(string username, string password) { ... }

---

✅ 요약: "좋은 주석은 이렇다!"

• ❓ 왜 그 코드를 썼는지 설명
• 🔍 복잡한 부분은 명확히
• 💡 핵심만 간결하게
• 🔄 코드와 함께 항상 최신 상태 유지
• 📌 함수/클래스에 요약 주석