Uniforme wijze van programmeren/scripten?

[A_De2]

Sinds enige tijd houd ik me op het werk bezig met het scripten met PowerShell. Ik ben absoluut geen expert hierin maar vermaak me prima en vind met behulp van internet (Hey Scriptingguy! etc) en Microsoftboeken genoeg hoe ik mijn scripts technisch inhoudelijk moet bouwen.

Nu zijn er meerdere mensen toegevoegd aan het team van scripters en het valt me op dat iedereen zijn eigen manier van scripts schrijven heeft. Voor de beheersbaarheid ben ik op zoek naar guidelines, tips&trucs, ideeën om onze scripts beheersbaar te houden. Dus dat iedereen scripts oplevert die volgens een standaard zijn opgebouwd.

Ik denk bijvoorbeeld aan vrij basic zaken als:
<#
.SYNOPSIS
Dit script doet blablabla
.DESCRIPTION
Output wordt blablabal
.NOTES
Gemaakt door A_De2 op datum blabla
Aangepast door A_De2 op datum blabla
#>

Maar ook spatiëring. Tabafstand van verschilllende pakketten wil nog wel eens afwijken. Zelf gebruik ik graag de meegeleverde ISE van Microsoft zelf.

Naast deze zaken ben ik met name op zoek naar diepere ideeën zoals hoe je scripts afvuurt. Zet je bijvoorbeeld eerst een New-PSSession op? Of gebruik je het lieftst Invoke-Command? Ik kan me voorstellen dat er meerdere wegen zijn die naar Rome leiden maar een "dit is de default, tenzij..." zou leuk zijn.

Ik ben benieuwd hoe jullie met bovenstaande omgaan!

[InZane]

A_De2 schreef op woensdag 05 november 2014 @ 12:57:
[knip]

Ik denk bijvoorbeeld aan vrij basic zaken als:
<#
.SYNOPSIS
Dit script doet blablabla
.DESCRIPTION
Output wordt blablabal
.NOTES
Gemaakt door A_De2 op datum blabla
Aangepast door A_De2 op datum blabla
#>

Maar ook spatiëring. Tabafstand van verschilllende pakketten wil nog wel eens afwijken. Zelf gebruik ik graag de meegeleverde ISE van Microsoft zelf.

Naast deze zaken ben ik met name op zoek naar diepere ideeën zoals hoe je scripts afvuurt. Zet je bijvoorbeeld eerst een New-PSSession op? Of gebruik je het lieftst Invoke-Command? Ik kan me voorstellen dat er meerdere wegen zijn die naar Rome leiden maar een "dit is de default, tenzij..." zou leuk zijn.

Ik ben benieuwd hoe jullie met bovenstaande omgaan!

Die 'gemaakt door' en 'aangepast door' vind ik altijd een beetje 1999 aanvoelen, want ik neem aan dat je tegenwoordig wel iets van GIT/TFS/SVN of een ander soort van versiebeheer gebruikt.

[ Voor 22% gewijzigd door InZane op 05-11-2014 13:06 ]

[Cloud]

Ik zou eerst bij Microsoft zelf gaan kijken, ze hebben er al aardig wat over geschreven namelijk

Denk dat je over het aanroepen van je scripts niet veel specifieks kunt vinden maar als je je aan de verb-noun zaken houdt en je maakt overal Cmdlets voor dan gaat het redelijk vanzelf denk ik.

[A_De2]

InZane schreef op woensdag 05 november 2014 @ 13:05:
[...]
Die 'gemaakt door' en 'aangepast door' vind ik altijd een beetje 1999 aanvoelen, want ik neem aan dat je tegenwoordig wel iets van GIT/TFS/SVN of een ander soort van versiebeheer gebruikt.

Is nog niet in place maar is wel zeer wenselijk en wordt binnenkort ingeregeld.

Cloud schreef op woensdag 05 november 2014 @ 13:08:
Ik zou eerst bij Microsoft zelf gaan kijken, ze hebben er al aardig wat over geschreven namelijk ...

Je hebt gelijk, onder andere jouw url had ik ook gevonden en dat zijn de basic zaken die gewoon in orde moeten zijn. Misschien moet ik een voorbeeldje geven van wat ik nu tegenkom; 2 scripts die hetzelfde doen maar toch net anders insteken:

Script 1
...
Enter-PSSession -Computername Server1
Do-Something
Exit-PSSession
...

Script 2
...
Invoke-Command -Computername Server1 -ScriptBlock {Do-Something}
...

Heeft misschien ook iets te maken met de manier hoe je de errorhandling uit de remote machine trekt?

[ Voor 19% gewijzigd door A_De2 op 05-11-2014 13:21 ]

[roviaro]

De enter/exit constructie is voor interactief gebruik, je moet dus de invoke methode gebruiken in een script. Die laatste geeft inderdaad de output van het scriptblock terug.

Powershell heeft diverse iteraties en daarmee gepaard gaande (syntax) wijzigingen wat het lastig maakt.

Ik zou headers doen op de manier zoals je al beschrijft (ik zou dit zelf minimaal houden, in de praktijk leest toch niemand de headers afgezien van een korte omschrijving en gebruik van de parameters).

Tabs/spaties zou ik ook uniform maken alsmede newlines als je met meerdere mensen in dezelfde source zit (handiger voor diffs).

Verder zijn er vaak diverse manieren om iets te doen met hun eigen quirks (bijvoorbeeld rond parallelle zaken, jobs enzo). Ook b.v. parameters voor functies kun je op meer manieren doen en je zit met eigenaardigheden met variables die typed zijn of niet. Daar kun je indien nodig regels voor opstellen om te voorkomen dat iedereen het wiel opnieuw uitvindt.

[A_De2]

Inmiddels heb ik een aantal boeken van Ed Wilson doorgepluisd en kom met een eigen beknopte shortlist met het oogpunt op beheersbaarheid waarbij met meerdere mensen aan scripts kan worden gewerkt. Daarom zo universeel mogelijk. Als jullie op- aanmerkingen of andere goede ideeën hebben: ik hoor ze graag!

Wall of text alert:

Scripting Guide Lines
- Do not use abbreviations; Use full cmdlet and full parameter names. Only exception will be for the error-action, “-EA”.
- Keep things as simple as possible.
- Design your scripts as if you’re never going to touch them again; Other people will have to be able to work with your scripts.
- Make no use of aliases. Aliases are personal and uneasy to read for others.
- Start with a short comment what a section of script or function does; not how because that could be subject to change.
- Do not over-comment:
#########################################
#
# PREPARE VARIABLES
#
#########################################
$computers = @()


- This is better:

# PREPARE VARIABLES
$computers = @()

- When creating a complex function with multiple code blocks, place an inline comment for each closing curly bracket. }
- At the beginning of the script, include an overview that describes the script, significant objects and cmdlets, and any unique requirements for the script.
- Use the verb-noun construction used by cmdlet names when naming functions. E.g. “show-diskspace”
- Always assume that parts of the script will be re-used for other scripts. Place comments to facilitate this process.
- NEVER assume current path. Use the full path via variable or named path.
- Document the version of Powershell the script was written for:
# Requires –version 2.0
- Avoid backticks “ ` ”:
Get-WmiObject -Class Win32_LogicalDisk `
-Filter "DriveType=3" `
-ComputerName SERVER2

Backticks are easily overread. So consider this:

$params = @{Class=Win32_LogicalDisk;
Filter='DriveType=3';
ComputerName=SERVER2}
Get-WmiObject @params

- Use native PowerShell!
- If you really must, use .net, external commands or COM object, in that order of preference. Document why you couldn’t use native PowerShell.
 

- Avoid pipelines in scrips:

Get-Content computer-names.txt |
ForEach-Object -Process {
Get-WmiObject -Class Win32_BIOS -ComputerName $_
}

Better:

$computers = Get-Content computer-names.txt
foreach ($computer in $computers) {
Get-WmiObject -Class Win32_BIOS -ComputerName $computer
}

- Avoid using flags to handle errors:
Try {
$continue = $true
Do-Something -ErrorAction Stop
} Catch {
$continue = $false
}

if ($continue) {
Do-This
Set-That
Get-Those
}

Instead, put the entire “transaction” into the Try block:
Try {
Do-Something -ErrorAction Stop
Do-This
Set-That
Get-Those
}
Catch
{
Handle-Error
}


 


Formatting the code
- Use 4 space tabs, as per default with the Microsoft Integrated Script Editor
- Line up curly brackets, with each nested block indented two (2) spaces.

- Block overview comments for a function or comment:

 

Creating functions
- Create specialized functions with just one (1) purpose.
- Make functions portable.
- When possible, line functions in alphabetical order for the purpose of readability.
- Name function descriptively, starting with “fun…”. E.g. FunDiskspace or FunCpulevel.

Variables
- Make use of focused variables. That means no recycling of variables.
- Use descriptive names. E.g. $servername and $ipaddress. Using $1 or $a is bad!
- Make use of a variables section at the beginning of the script. The only exception is when a variable is used within a function. In that case, keep the variable within the function.
- Do NOT EVER use hard-coding. Put everything in a variable!

[downtime]

Bedankt voor het posten van je lijst. Ik script ook in Powershell en hoewel ik de scripts meestal in m'n eentje schrijf ben ik in de loop der tijd veel van deze regels ook gaan hanteren.

Ik vraag me wel af waarom hij adviseert om geen pipelines te gebruiken. Ik gebruik een pipeline vaak als een mini-functie met een eigen scope, zodat objecten die je niet meer nodig hebt aan het einde van de pipeline vanzelf opgeruimd worden.
Je ziet dat ook in zijn voorbeeld. Door het resultaat van Get-Content aan de variabele $computers toe te wijzen blijf je zitten met een onnodig object wat je (eigenlijk) handmatig op moet ruimen omdat het anders blijft bestaan.

[Scr33x0r]

Voor PHP gebruiken we tegenwoordig PSR standaarden: http://www.php-fig.org/psr/ en dan met name 1 en 2 gaan over codestyle, zoals tabs, spatiering, maar ook waar de brackets moeten staan, hoe de indenting zit etc.

[A_De2]

downtime schreef op woensdag 14 januari 2015 @ 02:24:
...
Ik vraag me wel af waarom hij adviseert om geen pipelines te gebruiken. Ik gebruik een pipeline vaak als een mini-functie met een eigen scope, zodat objecten die je niet meer nodig hebt aan het einde van de pipeline vanzelf opgeruimd worden.
...

Ik begrijp uit zijn text dat het gebruik van constructs flexibeler is, beter kan performen en herbruikbaar is. Dit geldt overigens niet als je wat eenmaligs inramt via de cli.

[downtime]

Viel me nu pas op dat ie zichzelf hier tegenspreekt.

Use the verb-noun construction used by cmdlet names when naming functions. E.g. “show-diskspace”

Name function descriptively, starting with “fun…”. E.g. FunDiskspace or FunCpulevel.

Ik hanteer zelf trouwens de verb-noun conventie voor functienamen. Dat voelt logischer als je in PowerShell werkt.

[A_De2]

Verschil zit hem in cmdlets vs functions. Ik denk dat je door deze benamingen aan te houden, beter ziet waar je mee te maken hebt?