#Should I follow the PSScriptAnalyzer naming conventions for my module?

14 messages · Page 1 of 1 (latest)

queen laurel
#

Hey PowerShell peeps, I've got a couple "soft" questions around PowerShell naming conventions for my module. So I just put out a freshly minted prerelease module last night called GitClean (https://github.com/deadlydog/PowerShell.GitClean). It's very simple and the purpose is simply to run git clean -xfd across many local git repos. It only has one cmdlet, which I currently have named Clean-GitRepositories.

Clean-GitRepositories violates 2 PSScriptAnalyzer rules:

  1. Clean is not an approved verb.
  2. It wants me to not use plurals (by calling it Clean-GitReposiory)

Typically I try to follow the PSScriptAnalyzer conventions, but am conflicted in this case:

  1. Clean is a git operation, and there doesn't seem to be an approved verb that is similar to it.
  2. The whole point of the module is to clean multiple git repos. If I wanted to clean a single repo, I'd just use the native git operation without PowerShell.

I'm curious to get others' thoughts on this.

Do you think it's fine to use Clean as the verb? I'm not sure what I would use otherwise.
And do you think I should change it to the singular Repository, or does it make sense to stick with Repositories? This is the one I'm more conflicted about.

Thanks in advance!

tidal monolith
#

Pluras are ambiguous imo and always avoid them. Because is a plural cmdlet supposed to support a single object e.g? I'd say not.
Get-Verb ❤️ also

hushed leaf
#

yes, i would stick with only get-verb especially if you are publishing to the greater pwsh community.

#

if you want something more in line, I might try Clear-GitRepository

#

that might be more confusing though.

#

Or like Remove-GitUntracked would be more lower layer definition of what clean could be

#

stay singular though, I would say.

queen laurel
#

I thought about using Remove as well, but not something like Remove-GitUntrackedFiles. I hadn't considered Clear, but agree that it might be more confusing. I really wanted to use Clean in the cmdlet name to make it obvious which Git command was being ran.

I can't believe I didn't think of Invoke though, which I really like. I think something like Invoke-GitClean -ReposRootDirectoryPath $path still clearly communicates things.

Thanks team, I really appreciate the feedback! 😊

plucky thicket
#

I really do not like the invoke verb, because it's almost always used in situations like this, where you are just trying to avoid choosing an appropriate PowerShell verb.

However, the one place where it's reasonable is when your function is, literally, invoking some native command or remote API. Invoke-GitClean is totally fair.

Don't forget that you are also allowed to put an [Alias("....")] on your commands, so you can add one or more of the other things you would like to call it that way.

function Invoke-GitClean {
[Alias("git-clean","clean-repo", "clean-gitrepo")]
param(
#

Side note: did you know that you can actually add an alias with spaces: [Alias("git clean")] and then if you type git{tab} it will tab-complete to &'git clean'

hushed leaf
plucky thicket
#

Yeah, I mean git-clean is probably a better alias 😉

thorn crown
#

Same thing works with the function provider as well, item names are just locally unique strings 🙂

PS ~> Set-Content -Path "function:\git clean" -Value { Write-Host "I ain't cleaning sh#t, lol" }
PS ~> & 'git clean' # git{tab} will complete it too
I ain't cleaning sh#t, lol