코드 예제에 주석 추가하기

코드 주석 정보

코드 주석은 코드 예시가 수행하는 작업과 이유를 설명하여 더 긴 코드 예시를 설명하는 데 도움이 됩니다. 주석은 두 개의 창 레이아웃의 코드 예시 옆에 렌더링되므로 코드 자체의 가독성을 해치지 않으면서 더 긴 주석을 작성할 수 있습니다. 코드 조각이 아닌 전체 코드 예시에만 주석을 추가합니다. 코드 주석은 모든 코드 예시에 필요하지 않으며 반드시 필요한 경우에만 사용해야 합니다.

코드 주석은 다양한 대상 그룹에 유용할 수 있습니다. 코드 주석은 종종 신규 사용자에게 주요 개념을 설명하거나 경험이 풍부한 사용자에게 특정 선택지를 설명하는 데 사용됩니다.

새 사용자에게 코드 주석은 코드 예시의 개략적인 개요를 넘어 각 코드 줄이 수행하는 작업을 설명하여 친구나 동료가 코드를 안내하는 것처럼 코드를 이해할 수 있도록 하는 방법입니다.

경험이 많은 사용자에게 코드 주석은 코드 예시를 이해하고 특정 요구 사항에 맞게 조정하는 데 도움이 될 수 있습니다. 주석은 코드가 특정 방식으로 작성된 이유를 설명하여 기본 사항이 명확해지도록 합니다.

단일 문서에서 여러 코드 예시에 주석을 달 수 있지만, 각 주석은 문서의 복잡성을 증가시키고 화면 읽기 프로그램을 사용하는 사용자에 대한 반복적인 탐색 작업을 추가합니다. 문서에 여러 코드 예시가 있는 경우, 단일 예시로 결합할 수 있는지 여부를 고려합니다.

코드 주석 사용 및 추가하기

1. 문서의 layout: inline 프런트 매터 속성을 지정하세요.
2. 삼중 백틱을 사용하여 코드 예시를 만드세요.
3. 3중 백틱 뒤에 다음 annotate을(를) 잇는 코드 예시에 대한 언어를 지정하세요. 예를 들어 ```yaml annotate 또는 ```ruby annotate입니다.
4. 코드 예시 내에서 주석 태그(#, //, <&#33--, %%)를 사용하여 주석을 추가합니다. 코드 샘플이 작성된 언어에는 주석 태그를 사용해야 합니다. 예를 들어 YAML에는 #이고 JavaScript에는 //입니다.
   • 주석이 추가된 코드 예시는 반드시 한 줄 주석으로 시작해야 합니다. 첫 번째 코드 줄에 주석을 추가하지 않으려면 빈 주석으로 시작하면 됩니다.
   • 주석은 주석 태그 아래 줄의 코드에서 다음 주석 태그 또는 코드 블록의 끝에 적용합니다.

주석 규칙

다음의 규칙은 모든 코드 주석에 적용됩니다.

• /*처럼 여러 줄 스타일의 주석은 지원되지 않습니다.
• 코드 주석을 시작하는 기호와 주석 사이에는 공백이 있어야 합니다.
  • 올바른 사용: # comment
  • 잘못된 사용: #comment
• 빈 주석을 만들려면 그 뒤에 텍스트가 없는 설명 태그를 삽입하세요. 빈 주석은 샘플의 일부 줄에서 주석이 필요하지 않은 경우에 유용합니다.
• #!로 시작하는 문자열은 코드 블록에서 렌더링되며 주석으로 처리되지 않습니다.
• 설명 태그 뒤의 모든 항목은 Markdown으로 구문 분석될 것입니다. 링크, 버전 관리 및 기타 스타일은 Markdown에 작성된 것처럼 렌더링될 것입니다.
• 여러 순차 설명은 단일 주석을 만듭니다.
• 설명 태그로 시작하지 않고 비어 있거나 공백만 포함된 줄은 무시될 것입니다.
• 단일 줄의 설명을 사용하여 코드 구역을 시작해야 합니다. 코드의 첫 번째 줄(또는 구역)에 주석이 필요하지 않은 경우 텍스트가 없는 설명 태그를 사용하여 빈 주석을 만들 수 있습니다.
• HTML 스타일의 경우 주석 뒤에 닫는 태그 <!-- -->을(를) 포함하여, 구문 강조 표시를 유지 관리합니다.

코드 주석 모범 사례

코드 블록 앞의 소개를 사용하여 코드 예시의 전체 용도를 소개하고 주석을 사용하여 특정 코드 줄이 하는 작업과 해당 코드 줄이 수행하는 이유를 설명합니다.

코드 주석을 최대한 짧게 유지하는 동안 코드 주석의 명확성 우선 순위를 지정하세요. 코드 샘플을 자신의 작업에 대한 기초로 사용하므로, 주석은 작성되는 샘플과 다른 용도에 맞게 샘플을 조정하는 방법을 이해하는 데 도움이 됩니다.

코드 주석을 작성할 때 대상 그룹을 고려하고 예시가 특정 방식으로 작성된 이유를 사람들이 알 것이라고 가정하지 마세요.

주석은 주석이 달린 코드의 예상 결과를 표시하는 데 사용될 수 있지만, 전체 코드 예시의 결과는 대상 그룹에게 가장 적합한 방법이어야 하며, 여기에는 코드 예시 소개 또는 예시 다음에 설명하는 방법이 있습니다.

코드 예시가 변경되면 모든 주석이 여전히 유효한지 검사하세요.

주석이 추가된 코드 예시의 예시

다음 예시에서는 렌더링된 코드 주석의 모양과 해당 주석을 만드는 원시 코드를 보여 줍니다.

렌더링 예시

다음 코드 예시는 끌어오기 요청이 열릴 때 환영 메모를 게시하는 워크플로입니다.

# The name of the workflow as it will appear in the "Actions" tab of the GitHub repository.
name: Post welcome comment
# The `on` keyword lets you define the events that trigger when the workflow is run.
on:
  # Add the `pull_request` event, so that the workflow runs automatically
  # every time a pull request is created.
  pull_request:
    types: [opened]
# Modifies the default permissions granted to `GITHUB_TOKEN`.
permissions:
  pull-requests: write
# Defines a job with the ID `build` that is stored within the `jobs` key.
jobs:
  build:
    name: Post welcome comment
    # Configures the operating system the job runs on.
    runs-on: ubuntu-latest
    # The `run` keyword tells the job to execute a command on the runner.
    steps:
      - run: gh pr comment $PR_URL --body "Welcome to the repository!"
        env:
          GH_TOKEN: $
          PR_URL: $

name: Post welcome comment

on:

  pull_request:
    types: [opened]

permissions:
  pull-requests: write

jobs:
  build:
    name: Post welcome comment

    runs-on: ubuntu-latest

    steps:
      - run: gh pr comment $PR_URL --body "Welcome to the repository!"
        env:
          GH_TOKEN: $
          PR_URL: $

# The name of the workflow as it will appear in the "Actions" tab of the GitHub repository.
name: Post welcome comment
# The `on` keyword lets you define the events that trigger when the workflow is run.
on:
  # Add the `pull_request` event, so that the workflow runs automatically
  # every time a pull request is created.
  pull_request:
    types: [opened]
# Modifies the default permissions granted to `GITHUB_TOKEN`.
permissions:
  pull-requests: write
# Defines a job with the ID `build` that is stored within the `jobs` key.
jobs:
  build:
    name: Post welcome comment
    # Configures the operating system the job runs on.
    runs-on: ubuntu-latest
    # The `run` keyword tells the job to execute a command on the runner.
    steps:
      - run: gh pr comment $PR_URL --body "Welcome to the repository!"
        env:
          GH_TOKEN: $
          PR_URL: $

원시 코드 예시

The following code example shows a workflow that posts a welcome comment on a pull request when it is opened.

```yaml annotate
# The name of the workflow as it will appear in the "Actions" tab of the GitHub repository.
name: Post welcome comment
# The `on` keyword lets you define the events that trigger when the workflow is run.
on:
  # Add the `pull_request` event, so that the workflow runs automatically
  # every time a pull request is created.
  pull_request:
    types: [opened]
# Modifies the default permissions granted to `GITHUB_TOKEN`.
permissions:
  pull-requests: write
# Defines a job with the ID `build` that is stored within the `jobs` key.
jobs:
  build:
    name: Post welcome comment
    # Configures the operating system the job runs on.
    runs-on: ubuntu-latest
    # The `run` keyword tells the job to execute a command on the runner.
    steps:
      - run: gh pr comment $PR_URL --body "Welcome to the repository!"
        env:
          GH_TOKEN: $
          PR_URL: $
```