From: Jos Backus <jos@...>
Date: 2004-12-09T15:19:51+09:00
Subject: Re: [patch] Obtaining mode information on an IO object

On Thu, Dec 09, 2004 at 02:40:33PM +0900, James Britt wrote:
> >>Yes, it came from O_ACCMODE.
> >>cf. http://www.opengroup.org/onlinepubs/007908799/xsh/fcntl.h.html
> >>
> >>And ruby also has it.
> >> $ ruby -rfcntl -e 'p Fcntl::O_ACCMODE'
> >> 3
> >
> >
> >Hm, then again that in turn is a good argument for sticking with 
> >`accmode', as
> >it conforms to a known standard at least. Plus it's not too cryptic, is it?
> 
> Well, that's the question.  Who is the target audience, such that this 
> would be known, and what is gained from either name?
> 
> For those used to a certain sort of Unix C coding, many otherwise 
> cryptic names and commands are second nature, and carrying those names 
> over to a high level language conveys useful information.
 
Well, we are talking about a POSIX/OpenGroup interface here which as such is
standardized, and as Nobu points out has a precedent in terminology. As
Fcntl::O_ACCMODE is the official constant for the closely related file access
mode mask, I personally like its reflection in the name of the getter method,
`accmode'. But...

> On the other hand, there seems to be a general exhortation (certainly 
> something I've often seen mentioned among Rubyists) to write 
> self-documenting code and to use clear, descriptive names, rather than 
> terse abbreviations that save typing at the expense of long-term clarity.

I can clearly see this side of the argument as well. Then again, I'm not sure
if the term `access mode' is really clear to somebody who doesn't know the API
and would have to look it up anyhow.

> But see my first point; for the Unix-heads, "accmode" might be terribly 
> expressive.  For the rest of the world, people who code in Ruby unless 
> there is a compelling reason to drop down to C, "accmode" is probably 
> too terse.
 
Note: this is not necessarily about Unix/C but about programming against the
OpenGroup platform API, which brings with it certain nomenclature and defined
terms as part of the standardization effort.

> "access_mode" should be clear enough to both camps, unless there is 
> something about it's behavior that is tied to some special quality of 
> the Unix variant, or is likely something only to be of interest to those 
> accustomed to a certain low-level coding.
> 
> But maybe it's me; I still find myself writing, for example, [].unique, 
> only to be reminded that, in RubyWorld, 'unique' has a, um, uniq spelling.

Heh. Another idiom that traces its roots back to Unix; depending on one's
background this can be seen as either qt or obfuscating. I bet you won't
forget this method's peculiar name because of it though :)

Perhaps `accmode' and `access_mode' can be aliases? That would make these two
camps happy but perhaps upset a third party.

Cheers,
-- 
Jos Backus                       _/  _/_/_/      Sunnyvale, CA
                                _/  _/   _/
                               _/  _/_/_/
                          _/  _/  _/    _/
jos at catnook.com        _/_/   _/_/_/          require 'std/disclaimer'