InfoGrab DocsInfoGrab Docs

코드 주석

요약

자기 설명적인 코드 작성과 불필요한 주석 지양이 첫 번째 목표입니다. 코드가 충분히 자기 설명적이지 않은 경우, 주석은 코드만으로는 표현할 수 없는 맥락과 이유를 제공하는 데 중요한 역할을 합니다. 코드 주석은 코드 자체만큼 코드의 일부입니다.

핵심 원칙#

자기 설명적인 코드 작성과 불필요한 주석 지양이 첫 번째 목표입니다. 이는 설명적인 메서드 이름 사용, 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 코드베이스 전체에서 이러한 접근 방식이 혼재되어 있습니다. 어떤 경우든, 라이브러리가 더 넓게 사용될수록 문서화의 가치는 높아지고, 라이브러리의 구현 및 인터페이스 변경 빈도가 높을수록 가치는 낮아진다고 생각합니다.

후속 조치를 위한 주석#

향후 처리될 것으로 예상되는 코드 주석을 추가할 때마다 기술 부채 이슈를 생성하고, 생성한 코드 주석에 해당 이슈의 링크를 추가하세요. 이를 통해 다른 개발자들이 주석이 아직 유효한지, 처리하기 위해 무엇을 해야 하는지 빠르게 확인할 수 있습니다.

예시:

# Deprecated scope until code_owner column has been migrated to rule_type.
# To be removed with https://gitlab.com/gitlab-org/gitlab/-/issues/11834.
scope :code_owner, -> { where(code_owner: true).or(where(rule_type: :code_owner)) }

클래스 및 메서드 문서화#

메서드 인수나 반환 값을 문서화할 때는 YARD 문법을 사용하세요.

YARD 문법 없는 예시:

class Order
  # Finds order IDs associated with a user by email address.
  def order_ids_by_email(email)
    # ...
  end
end

YARD 문법을 사용한 예시:

class Order
  # Finds order IDs associated with a user by email address.
  #
  # @param email [String, Array] User's email address
  # @return [Array]
  def order_ids_by_email(email)
    # ...
  end
end

메서드의 반환 값이 사용되지 않는 경우, YARD의 @return 타입을 void로 표기하고 메서드는 명시적으로 nil을 반환해야 합니다. 이 패턴은 반환 값을 사용해서는 안 된다는 것을 명확히 하고, 체이닝이나 할당에서의 실수를 방지합니다. 예를 들어:

class SomeModel < ApplicationRecord
  # @return [void]
  def validate_some_field
    return unless field_is_invalid

    errors.add(:some_field, format(_("some message")))

    # Explicitly return nil for void methods
    nil
  end
end

자세한 맥락과 정보는 머지 리퀘스트 코멘트를 참조하세요.

코드 주석

GitLab v19.1
원문 보기
요약

자기 설명적인 코드 작성과 불필요한 주석 지양이 첫 번째 목표입니다. 코드가 충분히 자기 설명적이지 않은 경우, 주석은 코드만으로는 표현할 수 없는 맥락과 이유를 제공하는 데 중요한 역할을 합니다. 코드 주석은 코드 자체만큼 코드의 일부입니다.

핵심 원칙#

자기 설명적인 코드 작성과 불필요한 주석 지양이 첫 번째 목표입니다. 이는 설명적인 메서드 이름 사용, 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 코드베이스 전체에서 이러한 접근 방식이 혼재되어 있습니다. 어떤 경우든, 라이브러리가 더 넓게 사용될수록 문서화의 가치는 높아지고, 라이브러리의 구현 및 인터페이스 변경 빈도가 높을수록 가치는 낮아진다고 생각합니다.

후속 조치를 위한 주석#

향후 처리될 것으로 예상되는 코드 주석을 추가할 때마다 기술 부채 이슈를 생성하고, 생성한 코드 주석에 해당 이슈의 링크를 추가하세요. 이를 통해 다른 개발자들이 주석이 아직 유효한지, 처리하기 위해 무엇을 해야 하는지 빠르게 확인할 수 있습니다.

예시:

# Deprecated scope until code_owner column has been migrated to rule_type.
# To be removed with https://gitlab.com/gitlab-org/gitlab/-/issues/11834.
scope :code_owner, -> { where(code_owner: true).or(where(rule_type: :code_owner)) }

클래스 및 메서드 문서화#

메서드 인수나 반환 값을 문서화할 때는 YARD 문법을 사용하세요.

YARD 문법 없는 예시:

class Order
  # Finds order IDs associated with a user by email address.
  def order_ids_by_email(email)
    # ...
  end
end

YARD 문법을 사용한 예시:

class Order
  # Finds order IDs associated with a user by email address.
  #
  # @param email [String, Array] User's email address
  # @return [Array]
  def order_ids_by_email(email)
    # ...
  end
end

메서드의 반환 값이 사용되지 않는 경우, YARD의 @return 타입을 void로 표기하고 메서드는 명시적으로 nil을 반환해야 합니다. 이 패턴은 반환 값을 사용해서는 안 된다는 것을 명확히 하고, 체이닝이나 할당에서의 실수를 방지합니다. 예를 들어:

class SomeModel < ApplicationRecord
  # @return [void]
  def validate_some_field
    return unless field_is_invalid

    errors.add(:some_field, format(_("some message")))

    # Explicitly return nil for void methods
    nil
  end
end

자세한 맥락과 정보는 머지 리퀘스트 코멘트를 참조하세요.