Monad breaking change announcement: Approved verb names enforcement.

In order to prevent a mass usability nightmare with developers picking their own improvised cmdlet verbs, the Monad team, based on customer feedback, decided to enforce the use approved verbs.

The idea is to provide a more uniform and consistent interface to the end user. If a user needs to get something, he or she should know that what they are looking for is a get-something cmdlet. The user can then use the command discovery cmdlet (get-command get-*) to look for a getters and so forth...

With this change, if a non standard verb is to be used, the developer will be forced to add “__” to the beginning of the cmdlet name in order to make their cmdlet usable:

Example: in order to create a “play-nice” cmdlet where “play” is not an approved verb the developer will need to prepend the verb name with two underscore characters as follows “__play”.

Users can still get around this issue by simply aliasing the underscored cmdlet name as follows:

Set-Alias Play-Nice __Play-Nice

In order to ensure we have a complete list of valid verbs, we need to get your feedback on the list below to ensure we did not miss anything.

Please speak now or forever hold your peace J

Wassim

Comments

• Anonymous
  February 16, 2006
  Why are out, write, read lowercase and the rest mixed-case?

• Anonymous
  February 16, 2006
  Thank you pointing that out. No special reason. The mixed-case issue has been updated.
  
  Thanks
  Wassim [MSFT]
  

• Anonymous
  February 16, 2006
  Will those verbs make it to "VerbCommon"(http://windowssdk.msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref13/html/T_System_Management_Automation_VerbsCommon.asp) class in Msh API?
  
  If those verbs make it to "VerbsCommon" class, we wouldn't have to worry much about case-sensitivity for cmdlets containing common verbs.

• Anonymous
  February 16, 2006
  I am sorry for double posting.
  But i had to point out a typo in "Communications" section.
  
  If you go to "pair" column, you will see "receve" on "Send" row.

• Anonymous
  February 16, 2006
  Hmm, what about verbs for domains you haven't thought of?
  
  For example I'm creating some image processing cmdlets, e.g.
  
  resize-image, rotate-image etc.

• Anonymous
  February 16, 2006
  On the image verb examples I mean't to finish off with:
  
  So these will end up having to be:
  
  __resize-image, __rotate-image and will look "funny" unless users alias them.

• Anonymous
  February 17, 2006
  A comment on parameter naming rather than verbs:
  
  Please refrain from using 'PassThru' when 'PassThrough' is the correct term.  I am sure I am not the only reluctant user of 'International English' who will object!  It would be a breach of Microsoft's own coding guidelines to use 'inappropriate abbreviations/contractions for entity naming'
  
  Keep up the good work.  When do you expect to have a beta refresh that is standardised?
  
  "Now I've spoken, let's keep the peace"

• Anonymous
  February 17, 2006
  I was actually surprised to find Thru in the dictionary when this first came up as I was arguing for PassThrough as well.  Unfortunately I lost that argument when Thru was found in the dictionary.  http://dictionary.reference.com/search?q=thru
  
  Jeff Jones [MSFT]
  Monad Development
  Microsoft Corporation
  This posting is provided "AS IS" with no warranties, and confers no rights.

• Anonymous
  February 17, 2006
  I like the rules but are you worried that cmdlets will use the verbs but not keep the proper semantics? In other words, proper verbs will be used but the intended meaning will not be right? Is this better/worse? Probably better as I see it but wondering if this was thought about.
  
  To use Sean's example, I'm afraid someone might be too tempted to creat a Convert-Image rather than rotate-image.

• Anonymous
  February 17, 2006
  So it's Start-Music rather than Play-Music? And Limit-Image rather than Crop-Image? And Use-Image rather than View-Image or Display-Image (Write- or Get-Image would not be right). And Transform-* doesn't feel ike Convert-. Neither does Flush- feel like Clear-*. To me Flush-Buffer would be something completely different from Clear-Buffer. And what about Eject-Disc? Or Print-Report (you know, to a printer); or are we returning to Write-Report > LPT1: and teletype machines?
  
  I don't know. I think the guidelines are great. But to enforce them in such an intrusive manner, hmmmm... I think you're actualy forcing unnatural and therefore inconsistent verbs on people this way. Language is a fickle thing; don't think you can just call Limit-Language and be done with it.

• Anonymous
  February 17, 2006
  What happens to "format-table" and other formatting CmdLets? Do they now use the "write" verbs?
  
  About the non-approved verbs problem, couldn't there be a way to add "approved" verbs, just the same way you can add trusted providers and scripts? If the user/admin doesn't want the new verb to be approved, the CmdLets are used with the "__".

• Anonymous
  February 17, 2006
  I think lordabdul has an intersting idea.  What if MSH itself stuck on the leading "__".  That way I could write my cmdlets with a normal cmdlet name like resize-image.  Then by default in MSH you would have to type __resize-image to use the cmdlet unless the user specifically said the cmdlet (or snapin) is approved.  Then the user could just type resize-image.

• Anonymous
  February 18, 2006
  Thanks Keith.
  I'm wondering if the enforcement of "" and approved verbs is going to change anything anyway, especially if new CmdLets come with an installer that adds aliases to the common "profile.msh" script, in order to use the new commands without the "". This may need an admin approval... or not, since the installer is already launched with admin rights. So, from the user's point of view, this may not change anything... doesn't it?

• Anonymous
  February 18, 2006
  I agree with Ruben, this is going to make things worse, not better.  Suppose I want to see what the IP route table looks like, is that write-route?  I would expect write to take something and write it somewhere.  In that context, write does not replace display.  I agree that you need a list of approved verbs and I may even agree with some sort of enforcement but, you need to add LOTS more verbs to the approved list.
  
  It might be easier to come up with a list of unapproved verbs.

• Anonymous
  February 19, 2006
  Hi,
  Can I suggest putting a link to the monad download page in your sidebar?

• Anonymous
  February 20, 2006
  Monad では、コマンドレットの名前は [動詞]-[名詞] とするルールがあります。get-command や format-table といったように、動詞と、目的語となる名詞の組み合わせになっています。コマンドレットは簡単に追加することができ、やはりこのルールは守りましょうということになっていますが、さらに「動詞は、承認済みのものだけを使う」というルールが追加されることになりました。...

• Anonymous
  February 20, 2006
  I am wondering how "Initialize" in "Data Verbs" section can obsolet "erase" when the definition is to "prepare a resource for use"
  while "erase" is to be obsolete by "clear" verb in "Ubiquitous verbs" section.
  
  And yeah, another typo in obsoletes column of "join" in ubiquitous verbs; "1connect"

• Anonymous
  February 20, 2006
  This is a truly bad idea!  The proper verb committee can never get it right for everyone, for ever.  Set standards but allow others to decide when to break those standards.

• Anonymous
  February 22, 2006
  Bad idea. To illustrate:
  
  There's a verb for "out" but not for "in" or any opposite for "out".
  
  You're never going to get a complete list or even a list that will cover most eventualities; just thinking of general domains music, sound, video, graphics, HW access, user interaction, GUI's, etc. you're missing a load.
  
  To that you can add industry-specific domains like banking, insurance, manufacturing, etc., etc.
  
  I know Monad is predominantly aimed at SysAdmins but once it's there, users will use it to write functional scripts for whatever domains they're in.
  
  There's a reason why natural language is so rich...
  
  Anyway, have fun :-)

• Anonymous
  February 27, 2006
  Hi,
  Based on your feedback, the Monad development team decided not to go ahead with the approved verb enforcement change. Thank you all for your participation and for voicing your concerns.
  
  Wassim [MSFT]

• Anonymous
  February 28, 2006
  Entirely agree with Mark.You can provide "standard" list of available verbs but must be a way to reduce/extend it.
  
  Thanks.

• Anonymous
  April 11, 2006
  Why not noun-verb instead of verb-noun.
  Organizing methods with the data they operate on is arguably one of the core principles in OO programming.  I wouldn't even dare to count the number of methods in the .NET framework libraries (perhaps you could write a script) but could you imagine having MSDN library sorted by method then class?
  When I look for a function my first idea is to search for the concept, the verbs are often much more ambiguous then the concept for example if I want to search a csv file for specific all records containing XYZ I would want to look for commands that work with csv files, if forced to choose a verb I might try something such as "search" a csv file, "read" a csv file, "find" records in csv file, looking at the standard verbs might lead me to try "get" records from a csv.  And why is it export-csv but to write html output you have convert-html and is export-csv really anymore descriptive then write-csv.  
  The emphisis on verbs has also created the issue where the noun part no longer describes what is being manipulated but rather what is being created such as convert-html to what? or format-wide whats a wide? so searching for concepts like csv becomes a guessing game and and scanning lots of help.  I would much rather have longer unique verb/verb sentances then consistant verbs with unique but arbitrary nouns.  
  
  Aside from this issue, I'm very excited about MSH and think you've done an awsome job :)
  
  - Kurt

• Anonymous
  April 11, 2006
  Why not noun-verb instead of verb-noun.
  Organizing methods with the data they operate on is arguably one of the core principles in OO programming.  I wouldn't even dare to count the number of methods in the .NET framework libraries (perhaps you could write a script) but could you imagine having MSDN library sorted by method then class?
  When I look for a function my first idea is to search for the concept, the verbs are often much more ambiguous then the concept for example if I want to search a csv file for specific all records containing XYZ I would want to look for commands that work with csv files, if forced to choose a verb I might try something such as "search" a csv file, "read" a csv file, "find" records in csv file, looking at the standard verbs might lead me to try "get" records from a csv.  And why is it export-csv but to write html output you have convert-html and is export-csv really anymore descriptive then write-csv.  
  The emphisis on verbs has also created the issue where the noun part no longer describes what is being manipulated but rather what is being created such as convert-html to what? or format-wide whats a wide? so searching for concepts like csv becomes a guessing game and and scanning lots of help.  I would much rather have longer unique verb/verb sentances then consistant verbs with unique but arbitrary nouns.  
  
  Aside from this issue, I'm very excited about MSH and think you've done an awsome job :)
  
  - Kurt

• Anonymous
  April 12, 2006
  PingBack from http://blogs.msdn.com/monad/archive/2006/04/12/575056.aspx

• Anonymous
  April 12, 2006
  hi,Kurt:
  If you really love noun-verb.You can use this in your profile :
  foreach( $command in $(get-command -type cmdlet)) { set-alias "$($comman
  d.noun)-$($command.verb)" $command }
  

• Anonymous
  April 25, 2006
  PingBack from http://blogs.msdn.com/powershell/archive/2006/04/25/583267.aspx

• Anonymous
  April 29, 2006
  As a VMS sysadmin for years I came to just the opposite conclusion - years before object programming became available.  This is best demonstrated by the Queue commands.  You had to learn that queues could be Initialized, Set, Started, Stopped, Deleted, etc by looking in completely separate places of the help documentation.  You had to sift through all sorts of useless info (process, device, etc) that the verb also applied to to glean out the parts you actually needed.  If you didn't know the command to use (such as initialize vs. create) you had to hunt all over to get anything done (so much so, that a separate 'queue' entry was later created in the help files - one of very few non-command entries).  At the time I realized the architects of DCL had got it wrong, even if it was, initially, more inutitive - at least when tranlated into english.  
  
  However, do this for long and you realize that the first thing you think of is the noun, not the verb (i.e. I need a process or queue) - then you think of when and where to operate on that noun (lets create it here...) - so for the frequent user (the admin) - noun-verb is actually more intuitive thought process.
  
  - jon
  
  
  
  - jon

• Anonymous
  April 29, 2006
  The comment has been removed

• Anonymous
  June 05, 2008
  PingBack from http://green.onnix.co.cc/?p=54

• Anonymous
  June 01, 2009
  PingBack from http://uniformstores.info/story.php?id=19057