PowerShell'de Yorum nasıl eklenir?

Herhangi bir dilde kod yazarken yorum eklemek önemlidir. Bu aynı zamanda PowerShell betikleriniz için de geçerlidir. Bazen kısa olsalar da PowerShell'e yorum eklemek yine de önemlidir.

Yorumlar yalnızca başkalarının kodunuzu anlamasına yardımcı olmakla kalmaz, aynı zamanda kodunuzu okurken kendinize de harika bir hatırlatıcıdır. İşlevleri açıklamak için veya betiğinizin bazı kısımlarını yorumlamak için betiğinizi test ederken kullanılabilirler.

Bu yazımızda PowerShell’de nasıl yorum eklenir, yorum blokları nasıl kullanılır konularına bakacağız.

PowerShell'de yorum yapın

Çoğu programlama dilinde olduğu gibi PowerShell'de de yorum eklemek için # karakterini kullanabiliriz. Senaryolarınıza yorum eklerken her zaman düşüncelerinizi veya gerekçelerinizi açıklamaya çalışın. Veya bir fonksiyonun ne yaptığını kısaca açıklayın.

Bunun nedeni, iyi yazılmış bir PowerShell betiğinin genellikle oldukça açık olmasıdır. Aşağıdaki örneğe bakarsanız, yorumun gerçekten koda herhangi bir değer katmadığını görürsünüz.

# Get Admins
$admins = Get-Admins

Bu durumda daha iyi bir seçenek, ne elde ettiğimizi açıklamak olabilir:

# Get all users that have an admin role
$admins = Get-Admins

Yorumlar aynı zamanda kodunuzun bir kısmına veya bir fonksiyona yorum yapmak için de kullanılabilir. Bu genellikle betiğinizi test ederken ve onun bir kısmını atlamak istediğinizde kullanışlıdır. Atlamak istediğiniz işlevin önüne # eklemeniz yeterlidir; PowerShell işlevi yok sayar.

Örneğin aşağıdaki küçük scriptte 10 adet test dosyası oluşturuyoruz. Komut dosyanızı, dosyaları gerçekten oluşturmadan test etmek için, örneğin Yeni Öğe cmdlet'ini yorumlayabilirsiniz. Bu şekilde yalnızca Write-Host işlevi yürütülür.

# Path for the test files
$path = "C:\temp"

# Create 10 test files in the given path
1..10 | % {
    $newFile = "$path\test_file_$_.txt";
    # New-Item $newFile  # This cmdlet is skipped due to # infront of it
    Write-Host $newFile
}

PowerShell Blok Yorumu

Genel olarak yorumlarınızı kısa ve öz tutmanız önerilir. Ancak bazı durumlarda bir fonksiyonun ne yaptığını açıklamak için birden fazla satıra ihtiyacınız vardır. En fazla iki satırlık yorum için, her satırın önüne # karakterini kullanmakta sakınca yoktur.

Ancak daha fazlasına ihtiyacınız olduğunda PowerShell'de blok yorumu kullanmak daha kolay ve daha iyidir. Blok yorumun avantajı, yorumu kolayca düzenleyebilmeniz, IDE'nizde daraltabilmeniz (örneğin Visual Studio) ve bunların okunmasının daha kolay olmasıdır.

Aşağıdaki örnekte görebileceğiniz gibi, yorumunuz için yalnızca iki satıra ihtiyacınız olduğunda # karakteri düzgün çalışır:

# Storing the path of the log file for easy modification
# Changing this variable updates the log file location throughout the script.
$LogFile = "C:\Logs\output.log"

Ancak yorumlar daha uzun olduğunda yorum bloğu daha kullanışlı ve okunması daha kolay olur. Bir blok yorumu oluşturmak için onu <# ile başlatırsınız ve yorum bloğunu #> ile bitirirsiniz:

<#
    Get all the permissions of each mailbox
    
    Permission are spread into 4 parts.
    - Read and Manage permission
    - Send as Permission
    - Send on behalf of permission
    - Folder permissions (inbox and calendar set by the user self)
#>

İşlevler için Yorum Tabanlı Yardım

Komut dosyalarınız ve aslında işlevleriniz her zaman bir yorum bloğuyla başlamalıdır. Bu yorum bloğu belirli bir formatta yazılmıştır, bu okumayı kolaylaştırır ve ayrıca help cmdlet'i ile bilgileri görüntülememize olanak tanır.

Bu biçim, yoruma dayalı yardım olarak bilinir. Bir PowerShell yorum bloğunun içine yazılmıştır ve yorum bloğunu biçimlendirmek için yardım anahtar sözcüklerini kullanır. Yoruma dayalı yardım birkaç bölümden oluşmaktadır. Hepsini eklemenize gerek yoktur ancak Özet ve işlevin nasıl kullanılacağına dair en az bir örnek önerilir.

function Get-UserInfo {
    <#
    .SYNOPSIS
        Get the Microsoft 365 user information
    .EXAMPLE
        Get-UserInfo -Username 'meganb@contoso.com'

        This will get the M365 information of the given user
    #>
    [CmdletBinding()]
    param(
        # Microsoft 365 username
        [Parameter(Mandatory = $true)]
        [string]$Username
    )
    # Rest of the function code
}

Yoruma dayalı yardım bölümünü işlevinizin üstüne yerleştirmek yerine içine yerleştirmek en iyi uygulamadır. Bu şekilde, işlevde değişiklik yaptığınızda yorum yapmak için güncelleme yapmayı unutmanız daha zor olur.

İşleviniz parametreler kullanıyorsa, her parametreye hangi bilgileri beklediğinizi açıklayan yorumlar eklediğinizden emin olun.

Bir betiğin başlangıcına genellikle daha fazla bilgi eklersiniz. Komut dosyasının amacının ne olduğuna dair daha uzun bir açıklama, komut dosyasının nasıl kullanılacağına dair birkaç örnek ve son değişiklik tarihi, yazarı vb. bilgileri ekleyebileceğiniz notlar bölümü gibi.

<#
.SYNOPSIS
    A short one-line action-based description, e.g. 'Tests if a function is valid'
.DESCRIPTION
    A longer description of the function, its purpose, common use cases, etc.
.NOTES
    Information or caveats about the function e.g. 'This function is not supported in Linux'
.LINK
    Specify a URI to a help page, this will show when Get-Help -Online is used.
.EXAMPLE
    Test-MyTestFunction -Verbose
    Explanation of the function or its result. You can include multiple examples with additional .EXAMPLE lines
#>

Yorum Tabanlı Yardımı Kullanma

Yorum tabanlı yardım bloğunu komut dosyanıza veya işlevinize eklediğinizde, PowerShell'deki get-help cmdlet'ini kullanarak bu bilgileri görüntülemenize olanak tanır. Komutu herhangi bir parametre olmadan çalıştırırsanız, yalnızca işlevlerin özetini, açıklamasını ve sözdizimini gösterir.

Ancak yoruma dayalı yardım bölümündeki ek bilgileri göstermek için parametreleri kullanabiliriz:

  • -Ayrıntılı Örnekler de dahil olmak üzere komut hakkında daha ayrıntılı bilgi sağlar.
  • -Örnekler Komutun kullanım örneklerini görüntüler.
  • -Tam Ayrıntılı açıklamalar ve örnekler de dahil olmak üzere yardım içeriğinin tamamını gösterir.
  • -Çevrimiçi Komutun çevrimiçi belgelerini varsayılan web tarayıcısında açar.

Örneğin, MFA durum komut dosyamın ayrıntılı bilgilerini örneklerle görüntülemek istiyorsak şunları yapabiliriz:

Get-Help .\Get-MgMFAStatus.ps1 -Detailed

Kapanış

Bir komut dosyası yazarken PowerShell'inize yorum eklemek önemlidir. İşlevler yazdığınızda gerçekten mantıklı görünebilir ancak 6 ay sonra scripti güncellemeniz gerekirse yorumlar gerçekten kendi kodunuzu ve düşüncelerinizi anlamanıza yardımcı olabilir ?

Umarım bu makale size PowerShell'de yorumların nasıl kullanılacağını daha iyi anlamanızı sağlamıştır. Herhangi bir sorunuz varsa aşağıya bir yorum bırakmanız yeterli.

İlgili makaleler