# AI가 쓴 코드 주석에서 자주 보이는 아쉬운 9가지 패턴

- Link: https://qiita.com/jnchito/items/636c519c0b1d347c79b7?utm_campaign=popular_items&utm_medium=feed&utm_source=popular_items
- Discussion: https://startupxo.com/ko/1216/
- Posted by startupxo at 2026-11-01T00:48:29.059Z
- 0 points, 1 comment, kind story, origin curated
- Written in ko

## Summary

- 코드만 읽어도 알 수 있는 내용을 그대로 설명하는 주석이 많다. 원문은 이런 주석을 빼고, 꼭 필요할 때만 왜 그렇게 하는지 적으라고 권한다.
- 주석은 설명하려는 코드 바로 앞에 두어야 한다. 메서드 안의 특정 처리 설명을 메서드 정의 바로 위에 쓰면 전체 기능 설명으로 오해되기 쉽다.
- 과거 변경 이력이나 특정 호출 위치 같은 정보는 코드 주석보다 커밋 메시지, 풀 리퀘스트 설명, 호출하는 쪽 주석에 두는 편이 낫다고 원문은 설명한다.
- 원문 필자는 AI가 쓴 주석을 그대로 믿지 말고 사람이 검토해야 한다고 말한다. 주석 규칙을 CLAUDE.md 같은 AI 지침 파일로 정리하는 방법도 제안한다.

## Sources

- Qiita: https://qiita.com/jnchito/items/636c519c0b1d347c79b7?utm_campaign=popular_items&utm_medium=feed&utm_source=popular_items

## Comments (1)

- **startupxo** (editorial), 0 points, 2026-11-01T00:48:29.059Z, #c487
  O: Ruby로 작성된 코드 리뷰에서 AI가 단 메서드 정의 위 주석이 전체 기능 설명인지 특정 처리 설명인지 헷갈리는 팀원이, 원문의 두 번째 기준대로 주석 위치를 옮겨 보는 장면에 이 글이 쓸모 있습니다.
  X: 원문은 필자 개인의 Ruby 예시와 리뷰 경험에 기반하므로, 다른 언어나 팀 규칙에 그대로 옮기기 전에 맥락 차이를 확인해야 합니다.

JSON: https://startupxo.com/api/v1/item.json?id=1216&lang=ko