about_Comments

about_Comments

PowerShell에서 주석을 어떻게 쓰고, 주석이 특별한 의미를 갖는 경우가 어떤 게 있는지 살펴봐요. 코드를 읽는 사람을 위한 이 문서를 천천히 따라와 보시면 돼요.

출처: https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_comments

본문

간단한 설명

PowerShell 주석을 사용하는 방법과 특별한 사용 사례들을 정리해 봅니다.

자세한 설명

코드에 주석을 달아서 PowerShell 코드를 설명하거나 구조를 정리할 수 있어요. 가독성을 높이는 데 아주 유용하죠. 코드를 실행할 때 주석 텍스트는 PowerShell이 그냥 무시해 버려요.

주석은 코드를 읽는 사람에게 꼭 필요한 맥락을 전달해 줘요. 주석은 이런 목적에 쓰는 걸 권장드려요:

  • 복잡한 코드를 더 쉬운 말로 풀어서 설명
  • 특정 접근 방식을 선택한 이유 설명
  • 주의해야 할 엣지 케이스(edge case) 문서화
  • 참고 자료 링크 제공

일부 주석은 PowerShell에서 특별한 의미를 갖는데, 그 내용은 Special comments에서 다뤄볼게요.

PowerShell 주석 스타일

PowerShell은 두 가지 주석 스타일을 지원해요.

한 줄 주석(single-line comment) 은 해시 문자(#)로 시작해서 줄바꿈에서 끝나요. # 앞에는 주석에 속하지 않는 텍스트(공백 포함)가 와도 괜찮아요. 주석이 아닌 코드와 같은 줄에 붙어 있는 한 줄 주석을 "줄 끝 주석(end-of-line comment)"이라고 불러요.

블록 주석(block comment) 은 <#로 시작해서 #>로 끝나요. 블록 주석은 몇 줄이든 자유롭게 펼칠 수 있고, 주석이 아닌 코드의 앞, 뒤, 또는 중간 어디에도 넣을 수 있어요. 블록 안의 모든 텍스트(공백 포함)는 똑같은 주석으로 취급돼요.

중요: 블록 주석 안에 한 줄 주석을 넣는 건 가능해요. 그런데 블록 주석을 중첩하는 건 안 돼요. 중첩을 시도하면 바깥쪽 블록 주석이 처음 만나는 #>에서 끝나 버리거든요.

예제

예제 1: 한 줄 주석

# This is a single-line comment.
# This is also a single-line comment.

예제 2: 블록 주석

<#
    This is a block comment.
    Text within the block is a part of the same comment.
Whitespace is unimportant in a block comment.
#>

예제 3: 줄 끝 주석

$var = 4 # This is an end-of-line comment

예제 4: 인라인 블록 주석

'Foo'; <# This is an inline block comment #> 'Bar'

예제 5: 종합 예제

<#
    .DESCRIPTION
    Demonstrates PowerShell's different comment styles.
#>
param (
    [string] $Param1, # End-of-line comment
    <# Inline block comment #> $Param2
)

$var = 1, <# Inline block comment #> 2, 2

# Single-line comment.
# Another single-line comment.
$var.Where(
    <# Arg1 note #> { $_ -eq 2 },
    <# Arg2 note #> 'First',
    <# Arg3 note #> 1
)

특별한 주석(Special comments)

PowerShell에는 특정 용도로 쓰이는 주석 키워드가 몇 가지 있어요.

주석 기반 도움말(Comment-based help)

함수나 스크립트에 대한 주석 기반 도움말을 한 줄 주석이나 블록 주석으로 작성할 수 있어요. 사용자는 Get-Help cmdlet으로 함수나 스크립트의 주석 기반 도움말을 확인할 수 있죠. PowerShell은 설명이나 예제 사용법 같은 정보를 담을 수 있는 주석 키워드 15개를 정의해 두고 있어요.

<#
    .DESCRIPTION
    Comment-based help using a block comment.
#>
function Get-Function { }

# .DESCRIPTION
# Comment-based help using multiple single-line comments.
function Get-Function { }

자세한 내용은 아래를 참고해 주세요:

#Requires

#Requires 문은 현재 PowerShell 세션이 지정된 사전 요구 사항을 충족하지 않으면 스크립트가 실행되지 않도록 막아줘요. #Requires는 스크립트 어느 줄에 와도 상관없지만, 위치와 무관하게 똑같은 방식으로 처리돼요.

#Requires -Modules AzureRM.Netcore
#Requires -Version 6.0

param (
    [Parameter(Mandatory)]
    [string[]] $Path
)

자세한 내용은 about_Requires를 참고해 주세요.

서명 블록(Signature block)

스크립트는 PowerShell 실행 정책을 준수하도록 서명할 수 있어요. 서명을 하면 스크립트 끝에 서명 블록이 추가되는데, 이 블록은 여러 개의 한 줄 주석 형태로 되어 있어요. 스크립트를 실행하기 전에 PowerShell이 이 블록을 읽어요.

# SIG # Begin signature block
# ...
# SIG # End signature block

자세한 내용은 about_Signing을 참고해 주세요.

셔뱅(Shebang)

Unix 계열 시스템에서 셔뱅(#!)은 스크립트 시작 부분에 쓰는 지시문으로, 스크립트를 어떤 셸로 실행할지 알려줘요. 셔뱅은 PowerShell 언어의 일부가 아니에요. PowerShell은 셔뱅을 그냥 일반 주석으로 해석하고, 실제로는 운영체제가 셔뱅을 해석해요. 자세한 내용은 Wikipedia의 Shebang 문서를 참고하면 돼요.

아래 예제에서 셔뱅은 스크립트가 PowerShell이 아닌 다른 환경에서 호출될 때도 PowerShell이 이 스크립트를 실행하도록 해 줘요.

#!/usr/bin/env pwsh
Write-Host 'Begin script'

코드 편집기 영역 표시(Code editor region markers)

일부 코드 편집기는 코드 영역을 접고 펼칠 수 있는 영역 표시(region marker)를 지원해요. PowerShell에서 영역 표시는 #region으로 시작하고 #endregion로 끝나는 주석이에요. 이 영역 표시는 반드시 줄 맨 앞에 와야 해요. 영역 표시는 PowerShell ISE와 PowerShell 확장을 설치한 Visual Studio Code에서 지원돼요. 영역 표시는 PowerShell 언어의 일부가 아니고, PowerShell은 이를 그냥 일반 주석으로 취급해요.

자세한 내용은 Visual Studio Code 기본 편집 문서의 Folding 섹션을 참고해 주세요.

문자열 토큰 안의 주석

확장 가능한("...") 문자열이나 축자('...') 문자열 안에서는 #와 <# #>가 특별한 의미를 갖지 않아요. PowerShell은 이 문자들을 '말 그대로' 해석해요. 관련 규칙은 about_Quoting_Rules(단일 인용 문자열) 문서를 참고해 주세요.

PS> '# This is not interpreted as a comment.'
# This is not interpreted as a comment.

PS> "This is <# also not interpreted #> as a comment."
This is <# also not interpreted #> as a comment.

다만, PowerShell의 특정 기능들 중에는 주석이 들어 있는 문자열을 다루도록 설계된 것도 있어요. 주석을 어떻게 해석할지는 각 기능에 따라 달라져요.

정규식 주석(Regular expression comments)

PowerShell의 정규식(regex)은 .NET 정규식 엔진을 사용하는데, 이 엔진은 두 가지 주석 스타일을 지원해요:

  • 인라인 주석((?#))
  • 줄 끝 주석(#)

정규식 주석은 PowerShell의 모든 정규식 기반 기능에서 지원돼요. 예를 들어:

PS> 'book' -match '(?# This is an inline comment)oo'
True

PS> 'book' -match '(?x)oo# This is an end-of-line comment'
True

PS> $regex = 'oo # This is an end-of-line comment'
PS> 'book' -split $regex, 0, 'IgnorePatternWhitespace'
b
k

참고: 정규식의 줄 끝 주석은 (?x) 구문이나 IgnorePatternWhitespace 옵션을 함께 사용해야 동작해요.

자세한 내용은 아래를 참고해 주세요:

JSON 주석

PowerShell 6.0부터 ConvertFrom-Json cmdlet은 다음과 같은 JSON 주석 스타일을 지원해요:

  • 한 줄 주석(//)
  • 블록 주석(/* */)

참고: Invoke-RestMethod cmdlet은 받아온 JSON 데이터를 자동으로 역직렬화(deserialize)해요. PowerShell 6.0 이후 버전에서는 JSON 데이터에 주석이 허용돼요.

예를 들어:

'{
    "Foo": "Bar" // This is a single-line comment
}' | ConvertFrom-Json

Foo
---
Bar

경고: PowerShell 7.4부터 Test-Json cmdlet은 주석이 포함된 JSON을 더 이상 지원하지 않아요. JSON에 주석이 있으면 오류를 반환하죠. 7.4 이전 버전에서는 주석이 있는 JSON도 정상적으로 파싱했어요. PowerShell 7.5에서는 Test-Json에 JSON 주석을 무시하는 옵션이 추가되었어요.

CSV 주석

Import-Csv와 ConvertFrom-Csv는 W3C 확장 로그 형식(W3C Extended Log format)을 지원해요. 해시 문자(#)로 시작하는 줄은 주석으로 취급되어 무시되지만, 주석이 #Fields:로 시작해서 열 이름 목록을 구분자로 담고 있는 경우에는 예외예요. 그 경우 cmdlet은 그 열 이름들을 사용해요. 이 형식은 Windows IIS나 다른 웹 서버 로그에서 쓰는 표준 형식이에요. 자세한 내용은 Extended Log File Format을 참고해 주세요.

@'
# This is a CSV comment
Col1,Col2
Val1,Val2
'@ | ConvertFrom-Csv

Col1 Col2
---- ----
Val1 Val2

Windows PowerShell 5.1에서는 기본적으로 Export-Csv와 ConvertTo-Csv가 #TYPE 주석 형태로 형식 정보를 포함해요. PowerShell 6.0부터는 기본적으로 주석이 포함되지 않지만, IncludeTypeInformation 매개 변수로 이 동작을 바꿀 수 있어요.

[pscustomobject] @{ Foo = 'Bar' } | ConvertTo-Csv -IncludeTypeInformation

#TYPE System.Management.Automation.PSCustomObject
"Foo"
"Bar"

CSV 데이터에 #TYPE 주석이 포함되어 있으면, Import-Csv와 ConvertFrom-Csv는 이 정보를 사용해서 역직렬화된 개체의 pstypenames 속성을 설정해요.

class Test { $Foo = 'Bar' }
$test = [Test]::new()

$var = $test | ConvertTo-Csv -IncludeTypeInformation | ConvertFrom-Csv
$var.pstypenames

Test
CSV:Test

ConvertFrom-StringData 주석

ConvertFrom-StringData cmdlet은 문자열 데이터 안에서 #로 시작하는 줄을 주석으로 취급해요. 자세한 내용은 아래를 참고해 주세요:

참고 사항(Notes)

블록 주석은 중첩할 수 없어요. 아래 예제에서 Baz는 주석에 속하지 않아요.

<#
'Foo'
<# 'Bar' #>
'Baz'
#>

한 줄 주석 안에서는 <# #>가 특별한 의미를 갖지 않고, 블록 주석 안에서도 #는 특별한 의미를 갖지 않아요.

주석으로 취급되려면 주석 문자는 주석이 아닌 토큰(token)의 일부가 되면 안 돼요. 아래 예제에서 #Bar와 <#Bar#>는 Foo... 토큰의 일부예요. 그래서 주석으로 취급되지 않아요.

PS> Foo#Bar
Foo#Bar: The term 'Foo#Bar' is not recognized as a name [...]

PS> Foo<#Bar#>
Foo<#Bar#>: The term 'Foo<#Bar#>' is not recognized as a name [...]

더 알아보기