코드 주석

GitLab 코드베이스에서 코드 주석을 작성하는 원칙과 방법, YARD 문서화 문법 사용법을 설명합니다.

핵심 원칙 # 자기 설명적인 코드 작성과 불필요한 주석 지양이 첫 번째 목표입니다. 이는 설명적인 메서드 이름 사용, Ruby의 표현력 활용, 키워드 인수 사용, 작고 단일 목적의 메서드 생성, 관용적 규칙 준수, enum 사용 등을 통해 강화할 수 있습니다. 코드가 충분히 자기 설명적이지 않은 경우, 주석은 코드만으로는 표현할 수 없는 맥락과 이유를 제공하는 데 중요한 역할을 합니다. 코드 주석은 코드 자체만큼 코드의 일부입니다. 코드가 발전하거나 시스템에 대한 이해가 깊어짐에 따라 주석도 유지, 업데이트, 개선되어야 합니다. 따라야 할 핵심 원칙: 주석은 참조하는 코드에 최대한 가깝게 위치해야 합니다 주석은 철저해야 하되 중복을 피해야 합니다 이 코드를 다음에 읽는 사람은 맥락이 없고 이해할 시간이 제한되어 있다고 가정합니다 코드 주석은 "무엇"이나 "어떻게"가 아니라 "왜"에 더 집중해야 합니다 # 코드 자체가 무엇을 하는지 명확하게 표현해야 합니다. 주석 내에서 기능을 설명하면 추가적인 유지보수 부담이 발생하며, 코드가 변경될 때 주석이 구식이 되어 혼란을 야기할 수 있습니다. 대신, 주석은 특정 결정이 내려진 이유나 특정 접근 방식이 선택된 이유를 설명해야 합니다. 예를 들어: 시스템 한계를 우회하는 경우 즉시 명확하지 않을 수 있는 엣지 케이스를 처리하는 경우 깊은 도메인 지식이 필요한 복잡한 비즈니스 로직을 구현하는 경우 레거시 시스템 제약을 처리하는 경우 좋은 주석의 예: # Note: We need to handle nil values separately here because the external # payment API treats empty strings and null values differently. # See: https://api-docs.example.com/edge-cases def process_payment_amount(amount) # Implementation end 불필요한 주석의 예: # Calculate the total amount def calculate_total(items) # Implementation end 상위 수준 코드 주석 및 클래스/모듈 수준 문서화 # GitLab 코드베이스에는 여러 곳에서 재사용되는 많은 라이브러리가 있습니다. 이러한 라이브러리 중 일부(예: ExclusiveLeaseHelpers )는 내부 구현이 복잡하여 읽고 라이브러리 사용의 의미를 이해하는 데 시간이 많이 걸립니다. 마찬가지로, 이러한 라이브러리 중 일부는 매개변수의 이름만 읽어서는 이해하기 어려운 중요한 결과를 초래하는 여러 옵션을 가지고 있습니다. 이러한 라이브러리를 별도의 개발자 대상 Markdown 파일로 문서화해야 하는지 아니면 클래스/모듈/메서드 위의 주석으로 문서화해야 하는지에 대한 엄격한 지침은 없으며, GitLab 코드베이스 전체에서 이러한 접근 방식이 혼재되어 있습니다. 어떤 경우든, 라이브러리가 더 넓게 사용될수록 문서화의 가치는 높아지고, 라이브러리의 구현 및 인터페이스 변경