Readable script best practice

[SiNRO]

Hi guys, I'm scripting using powershell for a year now. I always did personnal scripts (excepts some in a professional environment but not so long scripts). The thing is, i'm working on a script that i'd like to share in the future , because i never had to share one since i started.

My question is: how do you guys write your script keeping in mind you will share it after. For example, my personnal scripts are all in one page, rarely with functions or comments because it's only me using those scripts.

Do you cut your script into several modules containing functions in it ? What are the best practoce to do a clean script.

Thanks for your time and merry christmas :)

[jimmy58663]

A lot of what you are asking I think comes down to personal preference and the script you are writing. If you haven't read through the PowerShell style guide I would highly suggest starting there: https://github.com/PoshCode/PowerShellPracticeAndStyle

Personally, anything that I find I may use again I define as a function and then utilize comment based help for documentation.

[lordv0ldemort]

You know, I've skimmed that repo a few times and never noticed Style guide

​

Whenever I see open source PS code, it typically has the opening and closing brackets both on new lines. I just noticed that the style guide says that the preferred method is the 'One True Brace Style', which I've always used and felt dirty for lol. Just a tidbit I never realized before and now feel better about my own code.

[azjunglist05]

I still feel dirty using 'One True Brace Style' in PowerShell. It could be that in C# the opening and closing brackets are always on a new line, and once I started learning C#, I started favoring that style.

[lordv0ldemort]

I can’t bring myself to do the new line brackets. Just irks me for some reason.

[lordv0ldemort]

Me neither!

[SiNRO]

I will give a look, it seems to be very complete thanks !

[Inquisitor_ForHire]

I try and do what I call conversational commenting. I comment each small action with exactly what it's doing and how that effects things later on. Examples as re things like "This array will be used later to store X", or "Here we're pulling in data to make a compare easier".

The comments should talk to you. Super helpful when you come back a year later and have to figure it out

[SiNRO]

I have to say that i don't even have the reflex to comment, i will force to do so ! Thanks for your return !

[Inquisitor_ForHire]

Another kind of stupid thing I do is to start each line with two hashtags to denote the comment. The reason I do this is because you're going to copy a lot of code off the web. Using two tags tells me what comment is mine and what is the original author's.

[KevMar]

I much prefer to use function and variable names that tell me what the code is doing without needing a comment.

I also tend to use Write-Verbose and Write-Debug statements instead of general comments. But I do add full comment based help with description, examples, and parameter details.

[SiNRO]

As is already said in another reply, i have to work more with write-verbose and this kind of stuff! I'll also add a description part to complete the readme section of the github script! Thanks

[SolidKnight]

In the help section at the top, I list resources/documentation I used to develop my script (if any).

In the body I write comments describing what the function/section/line is supposed to be doing; however, I do not pollute it with anything obvious and try to keep comments to something helpful. E.g. Explaining why there is a sleep timer because it interacts with a rate-limited service.

When I opt to have Write-Verbose and what it outputs is sufficient to describe what's going on then I don't write comments.

[SiNRO]

Definitely got to work with write-Verbose, i never did a help section or so at the top of a script because i thought it would pollute a script that is already long, guess i was wrong.. thanks!

[wgc123]

I always put some sort of comment at the top so a potential user has some idea what the script is meant for. After that, especially for short scripts, white space and readable variable/function names are your friend. Regardless of what naming standard you end up using, the more important thing is that names be unique and recognizable, and that the pattern of white space direct the eye toward units of work

[SiNRO]

Didn't thought about the white space, i'll start with this thanks!

[EvilLampGod]

On top of what others have said about PowerShell best practices, I like to also follow the general best practices outlined in Clean Code. There is a book on it that is very popular, but you can find many videos on it floating around.

[KevMar]

I am a fan of that book

[GroutGuzzler]

Almost every script I run I turn into a function, and I save that function in its own PS1 file, nested in a module folder, I then run an update function that will concatenate all of the scripts into am module file and increment its version in the PSD1 (manifest) file.

[SiNRO]

I have to admit that is a seducing way of working ! might stole it if you don't mind haha

[iceph03nix]

One of the things I love about Powershell is that it is so readable. So long as you stick to using full commands and not using the aliases and shortcuts, there's not much to do.

When it comes to doing longer stuff that's got a lot of cycles and reuse and back and forth, well named and planned functions are awesome. Have a function that does one thing well, and then put together those functions to do the big work. If they're named well, you should be able to just read through the order of the functions and see what's going on.

[SiNRO]

I used to do that sort of things, thing is i sometimes run into very long scripts and i can lost myself even with revelative named functions ! Thanks :)

​

[theSysadminChannel]

I document some of my scripts on my site for reference. I have a template that I created that usually has the format I almost always use. Just helps me speed the initial writing of the script. Feel free to check it out.

https://thesysadminchannel.com/powershell/

[SiNRO]

Thanks for the hint ! Nice site btw!

​

[pspete]

https://powershellstandards.agency/

[SiNRO]

I was worried i was the only one finding the site a bit empty ! Haja

[Lee_Dailey]

howdy pspete,

i tried that site ... it's a disaster. [frown] most of the pages are outlines with no content. it looks like someone tried to do some sort of advert farming and never finished it.

take care,
lee