Description
This is related to #181, but I need to go further than that. The ProvideVerboseMessage rule is nothing more than asking people to add noise to PowerShell. I'll explain.
This rule is completely broken right now, because it makes assumptions about when and how verbose should be used in PowerShell, and PSScriptAnalyzer simply cannot make those assumptions. Verbose output should only be used when it offers something of value to the caller. Full stop.
Consider the following examples:
A great example is Import-Module. Most of the time you don't care about verbose output, but if you load a module that internally tries to load a required module that fails to load, you don't get very good information in the output. In these scenarios, you should invoke Import-Module -Verbose so that you can see exactly what was going on when that module would not load. That helps figure out what the issue is on your side that may be preventing the command from succeeding.
Now consider Get-Command. If I want to see all commands that use the verb "Use", I would invoke this command: Get-Command -Verb Use. This is straightforward, and there is absolutely no reason for that command to generate any verbose output because it doesn't need to. Internally it just looks up commands on the system. I wouldn't like it much if that command included a "VERBOSE: I'm going to do what you told me to do now" type of message. That would be 100% noise. So, rightly so, Get-Command -Verb Use -Verbose does not generate any verbose output.
Going further, now think about advanced functions. Every function I create is an advanced function, not because it gives me verbose output, but because it gives me rich parameter binding, attribute validation, etc. And, if one of those functions does things that may be useful for an end user to know about should something go wrong, I will add Write-Verbose calls, but only if the commands I am invoking from my function do not already provide that verbose output themselves. See, no matter what you try to discover here with PSScriptAnalyzer, how you should actually use Write-Verbose depends completely on what you are doing internally, and no linting tool will ever be able to accurately determine that through static analysis of the code. The commands I invoke internally may already have verbose output. Or the function may be so simple that no verbose output should ever be generated. This rule right now is promoting what I would consider an anti-pattern: writing verbose output for the sake of writing verbose output. In my own module analysis, all that this command generates is noise, both in the analysis output, and in my code if I have to turn it off everywhere that I don't want it being noisy. PSScriptAnalyzer should absolutely not suggest that people should add verbose output for the sake of having verbose output. In fact, it simply shouldn't say anything at all about this.
Would you suggest someone add a comment similar to this in your code?
# Setting the i variable to 1
$i = 1
You shouldn't. That's just noise. This rule is just asking for people to create noise. Even if it is only informational, informational rules should only be used when they are generally useful, and this rule is not generally useful, so please, please, please, make it go away. :)