설명서에 코드를 포함하는 방법

아티클
08/10/2023

Microsoft Learn에 게시된 문서에 코드를 포함하는 스크린샷 이외의 여러 가지 방법이 있습니다.

한 줄에 개별 요소(단어) 포함

다음은 code 스타일의 예입니다.

텍스트에서 근접한 코드 블록의 명명된 매개 변수 및 변수를 참조하는 경우 코드 서식을 사용합니다. 속성, 메서드, 클래스 및 언어 키워드에도 코드 서식을 사용할 수 있습니다. 자세한 내용은 이 문서의 뒷부분에서 코드 요소를 참조하세요.
문서 Markdown 파일에 코드 블록 포함
```
    ```csharp
    public static void Log(string message)
    {
        _logger.LogInformation(message);
    }
    ```
```
코드 파일을 참조하여 코드를 표시하는 것이 비실용적인 경우 인라인 코드 블록을 사용합니다. 자세한 내용은 이 문서의 뒷부분에서 코드 블록을 참조하세요.
로컬 리포지토리의 코드 파일을 참조하여 코드 블록 포함
```
:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26":::
```
자세한 내용은 이 문서의 뒷부분에서 리포지토리 내부 코드 조각 참조를 참조하세요.
다른 리포지토리의 코드 파일을 참조하여 코드 블록 포함
```
:::code language="csharp" source="~/samples-durable-functions/samples/csx/shared/Location.csx" highlight="2,5":::
```
자세한 내용은 이 문서의 뒷부분에서 리포지토리 외부 코드 조각 참조를 참조하세요.
사용자가 브라우저에서 코드를 실행할 수 있는 코드 블록 포함
```
:::code source="PowerShell.ps1" interactive="cloudshell-powershell":::
```
자세한 내용은 이 문서의 뒷부분에서 대화형 코드 조각을 참조하세요.

이 문서는 이러한 각 코드 포함 방법에 대한 Markdown 설명은 물론, 모든 코드 블록에 대한 몇 가지 일반적인 지침도 제공합니다.

코드 요소

“코드 요소”는 프로그래밍 언어 키워드, 클래스 이름, 속성 이름 등입니다. 코드로 간주되는 요소가 항상 명확한 것은 아닙니다. 예를 들어 NuGet 패키지 이름은 코드로 처리되어야 합니다. 확실하지 않은 경우 텍스트 서식 지정 지침을 참조하세요.

인라인 코드 스타일

문서 텍스트에 코드 요소를 포함하려면 백틱(`)으로 둘러싸서 코드 스타일을 나타냅니다. 인라인 코드 스타일에서는 세 개의 억음 악센트 기호 서식을 사용하지 않아야 합니다.

마크다운	렌더링됨
기본적으로 Entity Framework에서 ‘Id’ 또는 ‘ClassnameID’라는 속성을 기본 키로 해석합니다.	기본적으로 Entity Framework는 `Id` 또는 `ClassnameID`로 명명된 속성을 기본 키로 해석합니다.

문서를 지역화(다른 언어로 번역)할 때 코드 스타일이 지정된 텍스트는 번역되지 않습니다. 코드 스타일을 사용하지 않으면 지역화되지 않도록 하려는 경우 지역화되지 않은 문자열을 참조하세요.

굵게 스타일

일부 이전 스타일에서는 인라인 코드에 굵게가 지정됩니다. 굵게는 코드 스타일이 너무 두드러져서 가독성이 저하되는 경우에 사용할 수 있는 옵션입니다. 예를 들어 대부분 코드 요소로 채워진 Markdown 테이블에서는 코드 스타일이 과도하게 적용될 수 있습니다. 굵게 스타일을 사용하도록 선택하는 경우 지역화되지 않은 문자열 구문을 사용하여 코드가 지역화되지 않도록 합니다.

링크

일부 컨텍스트에서는 코드 서식보다 참조 설명서 링크가 유용할 수 있습니다. 링크를 사용하는 경우 링크 텍스트에 코드 서식을 적용하지 마세요. 링크에 코드 스타일을 지정하면 텍스트가 링크인지 구분하기 어려울 수 있습니다.

링크를 사용하고 나중에 동일한 컨텍스트에서 동일한 요소를 참조하는 경우 후속 인스턴스는 링크가 아닌 코드 서식으로 만듭니다. 예시:

The first reference to <xref:System.CommandLine> in this text is a link.
Subsequent references to `System.CommandLine` can be in code style.

렌더링됨:

이 텍스트에서 System.CommandLine에 대한 첫 번째 참조는 링크입니다. System.CommandLine에 대한 후속 참조는 코드 스타일일 수 있습니다.

자리 표시자

사용자가 표시된 코드 섹션을 고유한 값으로 바꾸도록 하려면 꺾쇠 괄호로 표시된 자리 표시자 텍스트를 사용합니다. 예시:

az group delete -n <ResourceGroupName>

실제 값을 대체하는 경우 꺾쇠 괄호를 제거해야 한다고 언급해야 할 수 있습니다. Microsoft 작성 스타일 가이드에서는 꺾쇠 괄호 인라인 코드 내에 서식을 지정할 수 있는 기울임꼴을 사용하도록 합니다.

<ResourceGroupName>은 리소스 그룹입니다. 여기서...

중괄호({})는 구문 자리 표시자로 사용하지 않는 것이 좋습니다. 대체 가능 텍스트, 형식 문자열, 문자열 보간, 텍스트 템플릿 및 유사한 프로그래밍 구문에 사용되는 것과 동일한 표기법과 혼동될 수 있습니다.

자리 표시자 이름은 하이픈(“kebab case”) 또는 밑줄을 사용하여 구분하거나, 전혀 구분하지 않을 수 있습니다(파스칼식 대/소문자). Kebab case는 구문 오류를 생성할 수 있으며, 밑줄은 밑줄 표시(underlining)와 충돌할 수 있습니다. 모두 대문자는 자리 표시자 이름에 주의를 끌 수도 있지만 여러 언어에서 명명된 상수와 충돌할 수 있습니다.

<Resource-Group-Name> 또는 <ResourceGroupName>

코드 블록

문서에 코드를 포함하는 구문은 코드가 있는 위치에 따라 다릅니다.

문서 Markdown 파일에 있는 경우
동일한 리포지토리의 코드 파일에 있는 경우
다른 리포지토리의 코드 파일에 있는 경우

다음은 세 가지 유형의 코드 블록에 모두 적용되는 지침입니다.

스크린샷
코드 유효성 검사 자동화
주요 코드 줄 강조 표시
가로 스크롤 막대 사용 금지
잘못된 코드를 명확하게 식별

스크린샷

이전 섹션에 나온 방법은 모두 사용 가능한 코드 블록을 생성합니다.

복사하여 붙여넣을 수 있습니다.
검색 엔진에서 인덱싱됩니다.
화면 읽기 프로그램에서 액세스할 수 있습니다.

이는 문서에 코드를 포함하는 방법으로 IDE 스크린샷이 권장되지 않는 이유 중 일부분에 불과합니다. IDE 스크린샷은 IntelliSense와 같이 IDE 자체에 대한 어떤 정보를 표시하는 경우에만 코드용으로 사용하세요. 색 지정 및 강조 표시를 보여 주는 데는 스크린샷을 사용하지 마세요.

코드 유효성 검사

일부 리포지토리에는 모든 샘플 코드를 자동으로 컴파일하여 오류를 확인하는 프로세스가 구현되어 있습니다. .NET 리포지토리에서도 이렇게 합니다. 자세한 내용은 .NET 리포지토리의 기여를 참조하세요.

다른 리포지토리의 코드 블록을 포함하는 경우 코드 유지 관리 전략에 따라 소유자와 협력하여 코드에서 사용하는 라이브러리의 새 버전이 제공되어도 포함된 코드가 나뉘거나 최신 상태를 유지하지 못하는 일이 없도록 합니다.

강조 표시

일반적으로 코드 조각은 컨텍스트를 제공하는 데 필요한 것보다 많은 코드를 포함합니다. 이 예제와 같이 코드 조각에서 중점을 두는 주요 줄을 강조 표시하면 가독성에 도움이 됩니다.

Example showing highlighted code

문서 Markdown 파일에 포함할 때는 코드를 강조 표시할 수 없습니다. 코드 파일을 참조하여 포함된 코드 조각에만 사용할 수 있습니다.

가로 스크롤 막대

긴 줄을 나눠서 가로 스크롤 막대가 표시되지 않도록 합니다. 코드 블록에 스크롤 막대가 있으면 코드를 읽기 어렵습니다. 특히 스크롤 막대와 읽으려는 줄을 동시에 볼 수 없는 긴 코드 블록에서 문제가 됩니다.

코드 블록에서 가로 스크롤 막대를 최소화하는 좋은 방법은 85자보다 긴 코드 줄을 나누는 것입니다. 하지만 스크롤 막대의 유무가 가독성의 유일한 기준은 아니라는 점에 유의하세요. 줄을 85자 미만으로 나누면 가독성이나 복사-붙여넣기 편의성이 손상되는 경우 얼마든지 줄을 85자 이상으로 할 수 있습니다.

잘못된 코드를 명확하게 식별

일부 시나리오에서는 피해야 하는 코딩 패턴을 언급하는 것이 좋습니다. 예를 들면 다음과 같습니다.

시도하는 경우 컴파일러 오류가 발생하는 코드
올바르게 컴파일되지만 권장되지 않는 코드

이러한 시나리오의 경우:

코드 주석과 문서 텍스트 모두에서 오류를 설명합니다.

독자는 문서 텍스트를 건너뛰고 코드만 보는 경우가 많으므로 문서 텍스트에만 오류를 설명하는 것은 충분하지 않습니다. 코드 주석은 지역화되지 않으므로 코드 주석에서만 오류를 설명하는 것도 충분하지 않습니다.
컴파일러 오류를 일으킨다면 코드를 주석으로 처리하는 것이 좋습니다.

주석 처리된 코드는 문서의 리포지토리에 현재 하나 있거나 나중에 하나 구현되는 경우 CI(연속 통합) 시스템을 방해하지 않습니다.

권장되지 않는 코드를 제시하는 방법에 대한 예는 Rune 사용 예제: 문자 대/소문자 변경을 참조하세요. 이 예에서는 방지하기 위한 조언이 C# 메서드 이름이 ConvertToUpperBadExample인 것처럼 코드 자체로 작성됩니다.

인라인 코드 블록

코드 파일을 참조하여 코드를 표시하는 것이 비실용적인 경우에만 인라인 코드 블록을 사용합니다. 인라인 코드는 일반적으로 전체 프로젝트의 일부인 코드 파일보다 테스트 및 최신 상태 유지가 더 어렵습니다. 인라인 코드에는 개발자가 코드를 이해하고 사용하는 데 도움이 되는 컨텍스트가 생략될 수도 있습니다. 이러한 고려 사항은 주로 프로그래밍 언어에 적용됩니다. 인라인 코드 블록은 출력 및 입력(예: JSON), 쿼리 언어(예: SQL), 스크립팅 언어(예: PowerShell)에도 사용될 수 있습니다.

아티클 파일의 텍스트 섹션을 코드 블록 으로 나타내는 두 가지 방법이 있습니다. 즉, 삼중 백틱(''')으로 펜싱 하거나 들여쓰기합니다. 언어를 지정할 수 있는 펜싱을 사용하는 것이 좋습니다. 들여쓰기는 너무 간단하여 실수하기가 쉽고 다른 작성자가 문서를 편집해야 할 때 원래 작성자의 의도를 이해하기 어려울 수 있으므로 사용하지 않는 것이 좋습니다.

언어 표시기는 다음 예제와 같이 여는 backtick 3개 바로 뒤에 옵니다.

Markdown:

    ```json
    {
        "aggregator": {
            "batchSize": 1000,
            "flushTimeout": "00:00:30"
        }
    }
    ```

렌더링됨:

{
    "aggregator": {
        "batchSize": 1000,
        "flushTimeout": "00:00:30"
    }
}

팁

GitHub Flavored Markdown은 백틱(`)뿐만 아니라 물결표(~)로 코드 블록 구분을 지원합니다. 코드 블록을 열고 닫는 데 사용되는 기호는 동일한 코드 블록 내에서 일관되어야 합니다.

언어 표시기로 사용할 수 있는 값에 대한 자세한 내용은 언어 이름 및 별칭을 참조하세요.

백틱 세 개(```) 뒤에 지원되지 않는 언어 또는 환경 단어를 사용하는 경우 해당 단어가 렌더링된 페이지의 코드 섹션 제목 표시줄에 표시됩니다. 가능한 한 언어 또는 환경 표시기를 인라인 코드 블록에 사용하세요.

참고 항목

Word 문서에서 코드를 복사하여 붙여넣는 경우 코드에 유효하지 않은 “둥근 따옴표”가 없는지 확인합니다. 둥근 따옴표가 있으면 일반 따옴표(' 및 ")로 다시 변경합니다. 또는 학습 작성 팩, 스마트 따옴표 대체 기능을 사용합니다.

리포지토리 내부 코드 조각 참조

프로그래밍 언어에 필요한 코드 조각을 문서에 포함하려면 코드 파일을 참조하는 방법을 사용하는 것이 좋습니다. 이 방법을 사용하면 코드 줄을 강조 표시할 수 있고 개발자가 GitHub에서 더 넓은 범위의 코드 조각 컨텍스트를 사용하도록 할 수 있습니다. 학습 작성 팩의 도움을 받아 수동으로 또는 Visual Studio Code에서 삼중 콜론 형식(:::))을 사용하여 코드를 포함할 수 있습니다.

Visual Studio Code에서 Alt + M 또는 Option + M을 클릭하고 코드 조각을 선택합니다.
{b>코드 조각전체 검색범위 지정 검색리포지토리 간 참조
검색 용어를 입력하여 파일을 찾습니다. 파일을 찾으면 선택합니다.
다음으로, 코드 조각에 포함되어야 하는 코드 줄을 결정하기 위한 옵션을 선택합니다. 옵션은 ID, 범위 및 없음입니다.
4단계에서 선택한 옵션에 따라 필요한 경우 값을 입력합니다.

전체 코드 파일 표시:

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs":::

줄 번호를 지정하여 코드 파일의 일부 표시:

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26":::

코드 조각 이름을 지정하여 코드 파일의 일부 표시:

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" id="snippet_Create":::

다음 섹션에서는 이러한 예제를 설명합니다.

코드 파일의 상대 경로 사용
선택한 줄 번호만 포함
명명된 코드 조각 참조
선택한 줄 강조 표시

자세한 내용은 이 문서의 뒷부분에서 코드 조각 구문 참조를 참조하세요.

코드 파일의 경로

예시:

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26":::

이 예제는 ASP.NET 문서 리포지토리, aspnetcore/data/ef-mvc/crud.md 문서 파일에서 가져온 것입니다. 코드 파일은 동일한 리포지토리에 있는 aspnetcore/data/ef-mvc/intro/samples/cu/Controllers/StudentsController.cs의 상대 경로로 참조됩니다.

선택한 줄 번호

예시:

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26":::

위 예제에서는 StudentController.cs 코드 파일의 줄 2~24와 26만 표시됩니다.

다음 섹션에 설명된 대로 하드 코드된 줄 번호보다 명명된 코드 조각을 사용하는 것이 좋습니다.

명명된 코드 조각

예시:

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" id="snippet_Create":::

이름에는 문자와 밑줄만 사용합니다.

이 예제는 코드 파일의 snippet_Create 섹션을 표시합니다. 이 예제의 코드 파일에는 C# 코드의 주석에 코드 조각 태그가 있습니다.

// code excluded from the snippet
// <snippet_Create>
// code included in the snippet
// </snippet_Create>
// code excluded from the snippet

다음 예제에 표시된 것처럼 명명된 코드 조각은 중첩될 수 있습니다.

// <Method>
public static void SomeMethod()
{
    // <Line>
    // Single line of code.
    // </Line>
}
// </Method>

Method 코드 조각이 렌더링되면 Line 태그는 렌더링된 출력에 포함되지 않습니다.

가능한 한, 줄 번호를 지정하지 말고 명명된 섹션을 참조하세요. 코드 파일은 필연적으로 변경되고, 이 경우 줄 번호도 변경되기 때문에 줄 번호 참조는 불안정합니다. 항상 이러한 변경에 대한 알림을 받는 것은 아닙니다. 결국 문서에서 잘못된 줄이 나타나기 시작해도 무엇이 변경되었는지 알 수 없습니다.

선택한 줄 강조 표시

예시:

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26" highlight="2,5":::

이 예제에서는 표시된 코드 조각의 처음부터 줄 2와 5를 강조 표시합니다. 강조 표시할 줄 번호가 코드 파일의 처음부터 계산되지 않습니다. 즉, 코드 파일의 줄 3과 6이 강조 표시됩니다.

리포지토리 외부 코드 조각 참조

참조하려는 코드 파일이 다른 리포지토리에 있으면 코드 리포지토리를 ‘종속 리포지토리’로 설정합니다. 이 경우 이름을 지정합니다. 이 이름은 코드 참조를 위해 폴더 이름과 같이 작동합니다.

예를 들어 문서 리포지토리는 Azure/azure-docs이고, 코드 리포지토리는 Azure/azure-functions-durable-extension입니다.

azure-docs의 루트 폴더에 있는 .openpublishing.publish.config.json에 다음 섹션을 추가합니다.

    {
      "path_to_root": "samples-durable-functions",
      "url": "https://github.com/Azure/azure-functions-durable-extension",
      "branch": "main",
      "branch_mapping": {}
    },

이제 azure-docs에 있는 폴더처럼 sample-durable-functions를 참조할 때 실제로는 azure-functions-durable-extension 리포지토리에 있는 루트 폴더를 참조하게 됩니다.

학습 작성 팩의 도움을 받아 수동으로 또는 Visual Studio Code에서 삼중 콜론 형식(:::))을 사용하여 코드를 포함할 수 있습니다.

Visual Studio Code에서 Alt + M 또는 Option + M을 클릭하고 코드 조각을 선택합니다.
{b>코드 조각전체 검색범위 지정 검색리포지토리 간 참조리포지토리 간 참조
.openpublishing.publish.config.json에 있는 리포지토리에서 선택할 수 있습니다. 리포지토리를 선택합니다.
검색 용어를 입력하여 파일을 찾습니다. 파일을 찾으면 선택합니다.
다음으로, 코드 조각에 포함되어야 하는 코드 줄을 결정하기 위한 옵션을 선택합니다. 옵션은 ID, 범위 및 없음입니다.
5단계에서 선택한 옵션에 따라 값을 입력합니다.

코드 조각 참조는 다음과 같이 표시됩니다.

:::code language="csharp" source="~/samples-durable-functions/samples/csx/shared/Location.csx" highlight="2,5":::

azure-functions-durable-extension 리포지토리에서 해당 코드 파일은 samples/csx/shared 폴더에 있습니다. 앞에서 설명했듯이 강조 표시할 줄 번호는 파일의 시작이 아니라 코드 조각의 시작 부분을 기준으로 합니다.

참고 항목

종속 리포지토리에 할당하는 이름은 기본 리포지토리의 루트를 기준으로 하지만 타일(~)은 문서 세트의 루트를 나타냅니다. docset 루트는 에 의해 build_source_folder 결정됩니다 .openpublishing.publish.config.json. build_source_folder가 리포 루트(.)를 나타내므로 앞의 예제에서 코드 조각의 경로는 azure-docs 리포지토리에 포함됩니다. build_source_folder가 articles면 경로는 ~/samples-durable-functions가 아니라 ~/../samples-durable-functions로 시작합니다.

Jupyter Notebook의 코드 조각

Jupyter Notebook의 셀을 코드 조각으로 참조할 수 있습니다. 셀을 참조하려면 다음을 수행합니다.

참조할 셀의 Notebook에 셀 메타데이터를 추가합니다.
리포지토리에 대한 액세스를 설정합니다.
markdown 파일에서 Jupyter Notebook 코드 조각 구문을 사용합니다.

Notebook에 메타데이터 추가

Jupyter Notebook에서 셀 메타데이터를 추가하여 셀의 이름을 지정합니다.
- Jupyter에서 먼저 셀 도구 모음(보기 > 셀 도구 모음 > 메타데이터 편집)을 사용하도록 설정하여 셀 메타데이터를 편집할 수 있습니다.
- 셀 도구 모음을 사용하도록 설정했으면 이름을 지정하려는 셀에서 메타데이터 편집을 선택합니다.
- 또는 Notebook의 JSON 구조체에서 바로 메타데이터를 편집할 수 있습니다.
셀 메타데이터에서 “name” 특성을 추가합니다.
```
"metadata": {"name": "<name>"},
```
예시:
```
"metadata": {"name": "workspace"},
```
팁

셀이 사용되는 위치를 추적하는 데 도움이 되는 다른 메타데이터를 추가할 수 있습니다. 예시:
```
    "metadata": {
      "name": "workspace",
      "msdoc": "how-to-track-experiments.md"
    },
```

리포지토리 액세스 설정

참조하려는 Notebook 파일이 다른 리포지토리에 있으면 코드 리포지토리를 종속 리포지토리로 설정합니다.

Jupyter Notebook 코드 조각 구문 참조

Notebook에 필요한 메타데이터가 포함되면 markdown 파일에서 참조합니다. Notebook에 추가한 <cell-name-value>를 사용하고 <path>를 종속 리포지토리로 설정합니다.

[!notebook-<language>[] (<path>/<notebook-name.ipynb>?name=<cell-name-value>)]

예시:

[!notebook-python[] (~/MachineLearningNotebooks/train-on-local.ipynb?name=workspace)]

Important

이 구문은 블록 Markdown 확장입니다. 자체 줄에 사용해야 합니다.

<language> 식별자에 대해 지원되는 언어를 사용합니다.

대화형 코드 조각

인라인 대화형 코드 블록

다음 언어의 경우 브라우저 창에서 코드 조각을 실행 가능하게 만들 수 있습니다.

Azure Cloud Shell
Azure PowerShell Cloud Shell
C# REPL

대화형 모드를 사용하도록 설정한 경우 렌더링된 코드 상자에 시도 또는 실행 단추가 있습니다. 예시:

    ```azurepowershell-interactive
    New-AzResourceGroup -Name myResourceGroup -Location westeurope
    ```

은(는) 다음과 같이 렌더링됩니다.

New-AzResourceGroup -Name myResourceGroup -Location westeurope

And

    ```csharp-interactive
    var aFriend = "Maria";
    Console.WriteLine($"Hello {aFriend}");
    ```

다음과 같이 렌더링합니다.

    var aFriend = "Maria";
    Console.WriteLine($"Hello {aFriend}");

특정 코드 블록에 대해 이 기능을 켜려면 특수 언어 식별자를 사용합니다. 사용 가능한 옵션은 다음과 같습니다.

azurepowershell-interactive - 앞의 예제와 같이 Azure PowerShell Cloud Shell을 사용하도록 설정
azurecli-interactive - Azure Cloud Shell을 사용하도록 설정
csharp-interactive - C# REPL을 사용하도록 설정

Azure Cloud Shell 및 PowerShell Cloud Shell의 경우 사용자가 자신의 Azure 계정에 대해서만 명령을 실행할 수 있습니다.

참조하여 포함된 코드 조각

참조를 통해 포함된 코드 조각에 대해 대화형 모드를 사용하도록 설정할 수 있습니다. 특정 코드 블록을 대상으로 이 기능을 켜려면 interactive 특성을 사용합니다. 사용 가능한 특성 값은 다음과 같습니다.

cloudshell-powershell - 앞의 예제와 같이 Azure PowerShell Cloud Shell을 사용하도록 설정
cloudshell-bash - Azure Cloud Shell을 사용하도록 설정
try-dotnet - Try .NET을 사용하도록 설정
try-dotnet-class - 클래스 스캐폴딩으로 Try .NET을 사용하도록 설정
try-dotnet-method - 메서드 스캐폴딩으로 Try .NET을 사용하도록 설정

다음 몇 가지 예를 참조하세요.

:::code source="PowerShell.ps1" interactive="cloudshell-powershell":::

:::code source="Bash.sh" interactive="cloudshell-bash":::