{"id":1216,"kind":"story","title":"AI가 쓴 코드 주석에서 자주 보이는 아쉬운 9가지 패턴","url":"https://qiita.com/jnchito/items/636c519c0b1d347c79b7?utm_campaign=popular_items&utm_medium=feed&utm_source=popular_items","host":"qiita.com","by":"startupxo","score":0,"comments":1,"editorial_comments":1,"time":"2026-11-01T00:48:29.059Z","origin":"curated","language":{"source":"ko","reading":"ko","translated":false},"summary":["코드만 읽어도 알 수 있는 내용을 그대로 설명하는 주석이 많다. 원문은 이런 주석을 빼고, 꼭 필요할 때만 왜 그렇게 하는지 적으라고 권한다.","주석은 설명하려는 코드 바로 앞에 두어야 한다. 메서드 안의 특정 처리 설명을 메서드 정의 바로 위에 쓰면 전체 기능 설명으로 오해되기 쉽다.","과거 변경 이력이나 특정 호출 위치 같은 정보는 코드 주석보다 커밋 메시지, 풀 리퀘스트 설명, 호출하는 쪽 주석에 두는 편이 낫다고 원문은 설명한다.","원문 필자는 AI가 쓴 주석을 그대로 믿지 말고 사람이 검토해야 한다고 말한다. 주석 규칙을 CLAUDE.md 같은 AI 지침 파일로 정리하는 방법도 제안한다."],"discussion":"https://startupxo.com/ko/1216/","markdown":"https://startupxo.com/ko/1216.md","api":"https://startupxo.com/api/v1/item.json?id=1216&lang=ko","text":null,"edited":null,"sources":[{"site":"rss","name":"Qiita","url":"https://qiita.com/jnchito/items/636c519c0b1d347c79b7?utm_campaign=popular_items&utm_medium=feed&utm_source=popular_items","score":null,"comments":null,"observed_at":"2026-11-01T00:48:02Z"}],"thread":[{"id":487,"by":"startupxo","score":0,"time":"2026-11-01T00:48:29.059Z","text":"O: Ruby로 작성된 코드 리뷰에서 AI가 단 메서드 정의 위 주석이 전체 기능 설명인지 특정 처리 설명인지 헷갈리는 팀원이, 원문의 두 번째 기준대로 주석 위치를 옮겨 보는 장면에 이 글이 쓸모 있습니다.\nX: 원문은 필자 개인의 Ruby 예시와 리뷰 경험에 기반하므로, 다른 언어나 팀 규칙에 그대로 옮기기 전에 맥락 차이를 확인해야 합니다.","editorial":true,"replies":[]}]}