PowerShell Komut Dosyalarına Yorumlar Nasıl Eklenir?

PowerShell komut dosyalarına yorum eklemek, kodunuzu belgelemenin ve başkalarının (ve kendinizin) komut dosyanızın ne yaptığını anlamasını daha okunaklı hale getirmenin harika bir yoludur. Yorumlar, bir betiğin amacını ve mevcut farklı parametreleri açıklamak veya bir betiğin yürütülmesi hakkında ek bilgi sağlamak için kullanılabilir. Yorumlar ayrıca komut dosyasını değiştirmesi veya sorun gidermesi gerekebilecek diğer kullanıcılara talimat sağlamak için de kullanılabilir. Bu yazımızda PowerShell scriptlerine nasıl yorum ekleneceğini ve nasıl etkili bir şekilde kullanabileceğimizi ele alacağız.

PowerShell'de nasıl yorum yapılır?

Yorumlar PowerShell betikleri yazmanın önemli bir parçasıdır. PowerShell'de yorum eklemek için # (karma simgesi) ve ardından yorum metni söz diziminizi kullanın. Aynı satırda “#” sembolünden sonraki her şey yorumlayıcı tarafından göz ardı edilecek ve çalıştırılmayacaktır. İşte PowerShell yorum örneği:


# This is a single line comments
Write-Host "Hello, World!" # This is also a comment

Yukarıdaki örnekte, "Bu bir yorumdur" ve "Bu da bir yorumdur" ifadeleri, önünde "#" simgesi bulunduğundan çalıştırılmayacaktır. Başka bir deyişle, yorumlar aynı zamanda bir komut dosyasındaki kod satırlarını geçici olarak devre dışı bırakmak için de kullanılabilir. Belirli komutları çalıştırmadan bir komut dosyasında sorun gidermek ve test etmek istiyorsanız bu yararlı olabilir. Bunu yapmak için, komutun önüne # sembolünü eklemeniz yeterlidir; bu, komutun PowerShell yorumlayıcısı tarafından yoksayılmasına neden olur. Örneğin, bir cmdlet'i atlamak istiyorsanız aşağıdaki yorumu ekleyebilirsiniz:


# Get-Service -Name MyService # Skip this command.

Yorumlar, belirli bir kod satırının ne yaptığını, neden kullanıldığını ve nasıl çalıştığını açıklamak için kullanılabilir. Komut dosyasını okuyan veya değiştiren diğer kullanıcılara talimat veya uyarı sağlamak için de kullanılabilirler.

PowerShell'de Yorum Bloğu veya Çok Satırlı Yorum

PowerShell ayrıca çok satırlı yorumları da destekler. Çok satırlı yorum eklemek için yorumun başlangıcını ve bitişini işaretlemek üzere <# ve #> etiketlerini kullanmanız gerekir. Etiketler arasındaki herhangi bir metin yorum olarak değerlendirilir ve etiketlerin kendisi komut dosyasının bir parçası olarak yürütülmez. Bu, daha uzun yorumlar veya birden fazla kod satırına yayılan yorumlar için kullanışlıdır.


<#
    This is a multi-line comment that can be used to provide more detailed information about a script or function.
    For example, you can use it to explain the purpose of the script, the parameters it accepts, and how it should be used.
#>

Lütfen yukarıdaki örneklerin hepsinin yorumlara yönelik olduğunu unutmayın; PowerShell yorumlayıcısı yukarıdaki örneklerle yorumlanan satırların hiçbirini çalıştırmayacaktır.

PowerShell'deki parametrelere yorum ekleme

“#” sembolünü ve ardından yorum metninizi kullanarak parametrelere yorum ekleyebilirsiniz. Örneğin, “FilePath” adlı parametreye sahip bir komut dosyanız varsa ve parametrenin ne işe yaradığını açıklayan bir yorum eklemek istiyorsanız komut dosyanızın üst kısmına aşağıdaki satırı eklersiniz:


Function Get-FileSize
{
    param(
        # The path to the file to get size
        [parameter(Mandatory=$True)]
        [string]
        $FilePath
    )
    # Get file size in bytes
    $FileSize = (Get-Item -Path $FilePath).Length

    Return [math]::Round($FileSize/1KB,2)
}

#Call the function to get file size
Get-FileSize -FilePath "C:\temp\Applog.zip"

PowerShell'de yorum içeren İşlev şablonunu ekleyin

Yorumlar, kodunuzu belgelemenize ve komut dosyalarınızı okuyan veya değiştiren diğer kullanıcılara yararlı bilgiler sağlamanıza olanak tanır. PowerShell'de Yorumlar bloğuna sahip işlev şablonunun nasıl göründüğü aşağıda açıklanmıştır. Bu örnek aynı zamanda parametrelere nasıl yorum ekleneceğini de gösterir. Buna yoruma dayalı yardım denir, Get-Help cmdlet'ini kullandığınızda bu yorumlar görüntülenecektir!


<#
.Synopsis
   Add Prefix to All files
.DESCRIPTION
   Rename all files in a directory by adding a given prefix to each file name
.EXAMPLE
   Add-PrefixToAllFiles -FolderPath "C:\temp\Docs" -Prefix "Invoice"
.EXAMPLE
   Add-PrefixToAllFiles "C:\temp\Docs" "Invoice"
#>
Function Add-PrefixToAllFiles
{
    [CmdletBinding()]
    Param
    (
        # The path to the Folder where the files are located
        [Parameter(Mandatory=$true,
                   ValueFromPipelineByPropertyName=$true,
                   Position=0)]
        [string]
        $FolderPath,

        # The prefix to be added to the file names        
        [Parameter(Mandatory=$true,
                   ValueFromPipelineByPropertyName=$true,
                   Position=1)]        
        [string]
        $Prefix
    )

    Begin
    {
        # print a message
        Write-Host "Starting renaming of All files in $FolderPath..." -f yellow

    }
    Process
    {
        # Get all files in the specified Folder
        $Files = Get-ChildItem -Path $FolderPath -File

        # Loop through each file and rename it
        ForEach ($File in $Files) {
            $NewName = "$Prefix" + "_" + $File.Name
            Rename-Item -Path $File.FullName -NewName $NewName
        }
    }
    End
    {
        # Confirmation message
        Write-Host "All files in $FolderPath have been renamed with the prefix $Prefix." -f Green
    }
}

#Call the function to rename all files in a directory
Add-PrefixToAllFiles -FolderPath "C:\temp\Docs" -Prefix "Invoice"

Bu örnekte betiğin üst kısmındaki yorumlar betiğin amacını ve kabul ettiği parametreleri açıklar. Betiğin içindeki yorumlar her kod bloğunun amacını açıklar. Bu, gelecekte onu kullanması veya değiştirmesi gerekebilecek diğer kişiler için betiği daha okunabilir ve anlaşılması daha kolay hale getirmeye yardımcı olur.

Bu fonksiyon bloğunu PowerShell ISE'deki parçacıklardan gelen açıklamalarla ekleyebilirsiniz.

PowerShell'de yorumları kullanmaya yönelik En İyi Uygulamalar

Yorum oluştururken bunları açık ve öz tutmak önemlidir. Başkalarının aşina olmayabileceği aşırı karmaşık bir dil veya kısaltmalar kullanmaktan kaçının. Ayrıca senaryonuzun başına, ne yaptığını ve nasıl çalıştığını açıklayan yorumlar eklemek de iyi bir fikirdir. Bu, başkalarının senaryonuzu anlamasını ve kullanmasını kolaylaştıracaktır.

Bir başka iyi uygulama da herhangi bir karmaşık veya zor kodu açıklamak için yorumları kullanmaktır. Bu, başkalarının neler olduğunu anlamasına yardımcı olacak ve senaryonuzu korumayı kolaylaştıracaktır. Ayrıca, yazar, oluşturulma tarihi ve komut dosyanızın bilinen sorunları veya sınırlamaları gibi bilgileri içerecek şekilde yorumları kullanmak da en iyi uygulamadır. Ek olarak, komut dosyanızı mantıksal bölümlere ayırıp organize etmek için yorumları kullanmak iyi bir fikirdir; böylece anlaşılması ve gezinmesi kolaylaşır.

Yorumun okunmasını zorlaştırabileceğinden gereksiz kelime veya kelime öbekleri kullanmaktan kaçının. Ayrıca yorumlarınızın tutarlı olması da önemlidir. Örneğin, PowerShell'de belirli bir yorum yapma stili kullanıyorsanız komut dosyası boyunca aynı stili kullandığınızdan emin olun. Son olarak, komut dosyasını okuyan veya değiştiren diğer kullanıcılara yararlı bilgiler sağlayan anlamlı yorumlar kullandığınızdan emin olun. Bunları hizalı tutmayı ve okumayı kolaylaştırmayı unutmayın.

Çözüm

Sonuç olarak, PowerShell betiklerinize yorum eklemek kod yazmanın önemli bir parçasıdır ve kodunuzu düzenli, okunabilir ve bakımı kolay tutmanıza yardımcı olur. Başkalarının senaryonuzu anlamasını ve kullanmasını kolaylaştıran açıklamalar, notlar ve belgeler sağlarlar. Yorumlarınızı açık, kısa ve iyi organize ederek komut dosyanızın anlaşılmasının, bakımının ve sorunlarının giderilmesinin kolay olmasını sağlayabilirsiniz. Bu ipuçlarını takip ederek yorumlarınızın etkili ve faydalı olmasını sağlayabilirsiniz.

İlgili makaleler