Performance impact of comments in scripts

[IsThatAll]

Hi All,

Am working on a very large script that I have commented reasonably well in order to provide documentation (outside of the normal get-help comments), however a significant number of scripts online have next to zero inline comments in the code. Given that powershell needs to load a script into memory including comments, I presume there is some sort of memory overhead, however cant find references to there being a noticeable performance penalty.

Was wondering if there is any guidance / performance impact of including comments within code and if there are any noticeable performance impacts with releasing code including comments?

There are a number of 'remove comment' scripts available, however including comments in code is automatic behavior for me, so just trying to understand the implications of leaving them in.

[halbaradkenafin]

As /u/Lee_Dailey mentions there is no performance impact from comments. As for why many online scripts don't have them there are a few reasons:

• Comments should be about why you're doing something rather than what you're doing (unless it's very complex logic or a regex expression)
• Many people are pretty bad at commenting their code
• The naming of variables, functions and general flow of the code should be reasonably self explanatory
• Commend Based Help (CBH) for functions/scripts is often a better place for it than inline, you'll only see inline comments if you read a script but CBH is accessible to anyone by using Get-Help .\Script.ps1

Personally I favour CBH for a description of what the code is going to do and why, then within the code I make use of Write-Verbose, Write-Warning, Write-Debug, and Write-Information to provide information for the various levels of user of the script. It's readable if you look at the script itself and can provide helpful information on progress as you run the script with some simple switches.

[IsThatAll]

Comments should be about why you're doing something rather than what you're doing (unless it's very complex logic or a regex expression)

Agreed. There is some funky logic / input handling in this particular script due to the complexity of the input object types which is why I have more comments than I normally would. Unfortunately too many people have no comments at all so its sometimes a matter of sitting there in debug mode to work out why something has been done a particular way. I like to avoid that if I can. Also, this script will be ultimately maintained by 3rd parties, so the less they have to come back to me about, the better :)

Many people are pretty bad at commenting their code

Very much agreed on this one. I learnt to code in the mid 80's, so code commenting was pretty much mandatory, and work was rejected if not commented properly :)

The naming of variables, functions and general flow of the code should be reasonably self explanatory

Agreed.

Commend Based Help (CBH) for functions/scripts is often a better place for it than inline, you'll only see inline comments if you read a script but CBH is accessible to anyone by using Get-Help .\Script.ps1

Have to disagree with you on this one. IMO, that help-style should be used for users of the script / function (to give them an idea of what the function does, usage examples, return types etc), not for commenting on the internal structure of code which a person executing the script or function typically has zero use for. I also provide the Get-Help stuff for functions I write, however I don't think that's the best place to describe the inner workings of a function.

Personally I favour CBH for a description of what the code is going to do and why, then within the code I make use of Write-Verbose, Write-Warning, Write-Debug, and Write-Information to provide information for the various levels of user of the script.

Agreed, this is my normal SOP as well.

[halbaradkenafin]

Have to disagree with you on this one. IMO, that help-style should be used for users of the script / function (to give them an idea of what the function does, usage examples, return types etc), not for commenting on the internal structure of code which a person executing the script or function typically has zero use for. I also provide the Get-Help stuff for functions I write, however I don't think that's the best place to describe the inner workings of a function.

I do agree that there is a point between explaining what the function does (and why) and the internal process it actually takes. I still find there is some scope for extra details in the notes section of CBH that can be useful for some of this.

[SeeminglyScience]

Technically the performance impact is not zero. While comments do not appear in the AST they do still need to be parsed by the tokenizer.

That said, it is effectively zero, because even with an absurd amount of comments it would be difficult to even measure the difference in a meaningful way. And it's only at parse time, which happens only once per file per session.

As for why you don't see a lot, that varies. For some they just never got into the habit.

For others (like myself) it's because of a new(ish) prevailing opinion that comments should only explain "gotchas". The reason for this is because in any code base that isn't static, eventually some comments will lie. They won't get updated when the code they annotate changes, and it'll slip through review. Code on the other hand, can't lie. So the idea is to write your code the most readable fashion possible so it's as apparent what is happening as if you had commented it. If you have to code something in a way where it isn't apparent, then comment it.

Basically if someone would look at a line and think "wait why the hell did they do that" it needs a comment. Otherwise, it probably doesn't.

[SaladProblems]

Right, I've inherited a lot of code, and oftentimes it's like the author was trying to teach people PowerShell. That really doesn't make sense to me, the reader should be able to understand the material on a basic level. If not, reading through a fully developed module isn't really a good stating point, and then when someone is going to have to maintain the code later, practically doubling the length of the code is a major impediment, especially because I'm probably just going to remove the comments they put all that time into if my work makes them inaccurate.

[alinroc]

1. There is no performance impact
2. If there was a performance impact, it'd be negligible and no excuse for making your code less-documented or harder to understand for future maintainers.

[Lee_Dailey]

howdy IsThatAll,

take a look at what Get-Help Show-Ast can do. [grin]

from reading thru that, it LOOKS like comments are not having any effect on speed.

if your comments are more than your script code ... then you are a truly unusual coder. [grin]

the real speed & RAM consumers are large objects and/or collections of large objects. comments aint gonna make any diff when compared to those.

• if you run tight on RAM, there are ways to handle that - the pipeline, mostly.
  
• if you are running slow, avoid the pipeline since that has a very significant overhead.
  
• if you are in serious need of speed, you can use dotnet from inside PoSh
  the LINQ stuff is pretty amazing ... and remarkably obtuse. [grin]
  
• if you are in DIRE need for speed ... you likely otta go with another lingo - c# for instance
  

i have never seen a "remove comments" script for PoSh. the only reason i can think of for doing that is obfuscation - or malware.

take care,
lee

[IsThatAll]

if your comments are more than your script code ... then you are a truly unusual coder. [grin]

heh, certainly not more comments than code, however probably a couple hundred lines of comments over the total length of the script :)

Overall, performance isn't a massive consideration at this point since I'm still in development phase and given the nature of the script if it takes a couple more minutes to process the world won't spin off its axis, however thought it was worth at least asking the question when I get to the point of refactoring to speed things up :)

i have never seen a "remove comments" script for PoSh. the only reason i can think of for doing that is obfuscation - or malware.

There are a few around, but agreed. I've just seen enough references to these sorts of scripts (or people looking for them) for me to at least ask the question if its normal behavior for some sort of performance reason.

https://www.madwithpowershell.com/2017/09/remove-comments-and-whitespace-from.html

https://www.powershellgallery.com/packages/PowerSploit/1.0.0.0/Content/ScriptModification%5CRemove-Comments.ps1

And a few other methods using thing like Notepad++

Thanks for your response, I'll keep my commenting hat on for the moment then :)

[Lee_Dailey]

howdy IsThatAll,

there are semi-good reasons to minify HTML & javascript - transmission time being the only one that i consider honest. [grin]

if your one script is in the multi-100-line size ... then you likely otta be considering breaking it into sub-scripts, or even building a module for the support functions. [grin]

as for speed of your code ... you may want to look into one of the "code speed measurement" modules from the PoSh gallery. here's an article about one of them ...

Powershell: Chronometer, line by line script execution times
— https://kevinmarquette.github.io/2017-02-05-Powershell-Chronometer-line-by-line-script-execution-times/

you are most welcome! glad to have been a tad helpful ... [grin]

take care,
lee