From: Panu Viljamaa <panu@...>
Date: 2001-12-22T00:34:14+09:00
Subject: [ruby-talk:29235] Principle of Ethical Software Design (Re: Quantitative Unit-testing?  (Re: John Roth dolt (  Re: A challenge   to   proponents of Unit  Testing. )

Marc Gluch wrote:

> ...
> I'm all for intention revealing selectors (and more generally,
> intention revealing names), but you left out a discussion
> of tradeoffs in naming parameters after their types
> vs their roles in the method.

An excerpt  from  http://members.fcc.net/panu/SRNC-ST.htm   discusses this:

" ...  4.1.2 Is it good to have some semantic information in the argument names, e.g., 'nameString'?
In our opinion No. If the keywords already indicate semantics it would be redundant to add it to
the argument as well. Taking semantics away from keywords is bad because it makes calling
code harder to understand - since any information about the formal argument names is not
visible in the calling places. But to allow a maximal coverage of existing practices, any lower
case prefix is allowed ... "

I may not completely agree with the above in practice. Depending on the situation I sometimes use argument names such as  'nameString' that convey some of the semantics. However the important thing to realize is the 'forces' behind this decision.  Compare these three:

A)
    registerPerson: nameString
     " ..."
B)
     registerPersonNamed: aString
    "  ... "
C)
     registerPersonNamed: nameString
    "  ... "

Alternative C contains redundancy (named/name) thus making  the method header longer than needed without adding new information. So I'd rule that out immediately. Longer code is harder to read.

What about A and B ?  They seem to convey the same semantics. But are they as good ? As I argue in the excerpt, C is better because then the semantics is visible *at the places where the method is called*. Consider that your method is called from 100 places. With alternative A) you would have 100 places in your program/library where to the reader of the program it is not immediately clear about what type of an argument is expected by the method. Should it be an instance of Person or an instance of String ?

Wouldn't  this be obvious  from the calling context ? Not necessarily because the actual argument that is passed may be an argument of the calling method - confusingly named - or some value derived from it through elaborate processing via local variables, manipulated within loops and multiple levels of conditionals..

With alternative B) there is no confusion either in the method-header, or in the calling places. Even though you may think that " registerPerson: nameString  " looks nicer as a method-definition, don't forget that what is more importantactually is how the places where the method is called from look - because there are more of them.

This comes down to what I call "Principle of Ethical Software Design". If you were a library vendor that creates classes and methods you never use yourself, you might prefer alternative A). It "looks nicer". It might  attract more users to your class library because of that. So you 'sell' more of your library then (selfishly!). However, if you're 'ethical', you take some time to think about your fellow programmer who actually needs to create working software with your methods. You then realize that what really matters is not the clarity of *your* method-headers, but the clarity of *their* software created by using your headers. Thus you'd prefer alternative B, ethically.

-Panu Viljamaa