Go Coding Standards

기본 원칙

한 함수는 한 가지 일만

• 함수 이름이 "and" 혹은 "or"로 연결되는 상황이면 분리 신호
• 테스트 케이스가 if 분기마다 필요하면 분리 신호

조건문과 반복문의 depth는 2단계까지만 허용

• 최대한 early return으로 depth 줄이기
• 그조차 무거워지면 별도 함수로 분리

함수의 사이드 이펙트는 명시할 것

• 예: getUser가 updateLastAccess()도 실행한다면 함수명에 명시

가능하면 매직 넘버/문자열은 상수화

• 사용처 파일 상단에 선언
• 상수가 많아지면 상수 파일 분리 검토

함수 순서는 호출 순서대로

• Go의 명확한 컨벤션이 있다면 해당 규칙 따르기
• 그 외에는 위에서 아래로 읽기 쉽게 호출 순서대로

구현이 복잡해지면 외부 라이브러리 사용 검토

• 로직이 복잡하여 테스트 코드까지 비대해지는 상황
• 업계 표준 라이브러리가 있다면 사용
• 보안, 정확성, 성능 최적화가 핵심인 경우
• 플랫폼 호환성, 엣지 케이스가 많은 경우

모듈화(코드 복붙 및 패턴 반복 방지)

• 코드 반복을 절대적으로 금지
• 비슷한 패턴도 재사용 가능한 형태로 모듈화
• 재사용이 확정적이면 미리 모듈화 허용
• 과도한 추상화는 피하기
• 모듈화 레벨:
  • 같은 파일: 별도 함수로 추출
  • 여러 파일: 별도 패키지로 분리
  • 여러 프로젝트/도메인: 별도 모듈로 분리

변수, 함수명

• 목적을 명확히 하면서도 간결하게
• 업계 표준 축약어(id, api, db, err 등) 외 축약어 금지
• 상위 컨텍스트 정보는 반복하지 않기
• boolean 변수는 is, has, should 등 접두사
• 함수명은 동사 혹은 동사+명사 형태
• 복수형 규칙:
  • 순수 배열/슬라이스: "s" 접미 (users)
  • 래핑된 구조체: "list" 접미 (userList)
  • 특정 자료구조: 명시 (userSet, userMap)
  • 이미 복수형인 단어: 그대로 사용

필드 순서

• 기본적으로 알파벳 오름차순
• 사용처에서도 일관성 유지

에러 처리

• 에러 처리 레벨: 의미 있는 대응 가능한 곳에서 처리
• 에러 메시지: 로그엔 기술적 세부사항, 사용자엔 실행 가능한 가이드
• 에러 분류: 예상 가능한 에러와 예상 불가능한 에러 구분
• 에러 전파: 호출 스택 상위로 전파 시 컨텍스트 추가
• 복구 vs 빠른 실패: 예상 가능한 에러는 폴백으로 복구
• 에러 체인이 필요하면 %w, 단순 로깅용이면 %v 사용
• 외부로 노출하면 안 되는 내부 에러는 %v로 랩핑
• 에러를 반환하는 함수의 return error는 절대 무시하지 말고 명시적으로 처리
• Sentinel 에러: 호출자가 처리해야 하는 예상 조건은 var ErrNotFound = errors.New("not found")

파일 구조

파일 내 요소 순서

1. package 선언
2. import문 (그룹화)
3. 상수 정의 (const)
4. 변수 정의 (var)
5. Type/Interface/Struct 정의
6. 생성자 함수 (New*)
7. 메서드 (리시버 타입별 그룹화, 알파벳순)
8. 헬퍼 함수 (알파벳순)

인터페이스와 구조체

인터페이스 정의 위치

• 인터페이스는 사용하는 패키지에 정의 (Accept interfaces, return structs)
• 여러 패키지에서 공통으로 쓰는 인터페이스만 별도 패키지

포인터 리시버 규칙

• 상태 변경, 큰 구조체(3개 필드 이상), 일관성이 필요한 경우 포인터 리시버
• 나머지는 값 리시버

Context 사용

Context 파라미터

• 항상 첫 번째 파라미터로 전달
• context.Background()는 main과 테스트에서만 사용

테스트

테스트 라이브러리

• assertion 라이브러리(testify 등)보다 표준 라이브러리의 if + t.Errorf 선호
• mock은 gomock보다 수동 구현 선호

금지 사항

init() 함수

• 왠만해서 사용 금지. 명시적 초기화 함수 선호

패키지 구조

internal 패키지

• 라이브러리는 적극 활용, 애플리케이션은 필요시만

추천 라이브러리

• 웹: Fiber
• DB: Bun, SQLBoiler(외부 마이그레이션 관리 시)
• 로깅: slog
• CLI: cobra
• 유틸리티: samber/lo, golang.org/x/sync
• 설정 관리: koanf(cobra 통합 필요한 경우 viper)
• 유효성 검증: go-playground/validator/v10
• 스케줄링: github.com/go-co-op/gocron
• 이미지 처리: github.com/h2non/bimg