I am wondering what's the common naming convention for variables and
parameters.
I need to properly name a variable which can be a pathname or a stream
or a function (closure).
Is it pathname-stream-function or should it be pathname-or-stream-or-
function?
Can it be something shorter like path-designator (too vague/
misleading?)?
Thank you,
Andrew
From: Kent M Pitman
Subject: Re: Need help in naming a variable
Date:
Message-ID: <uejklkv90.fsf@nhplace.com>
Trastabuga <·········@gmail.com> writes:
> I am wondering what's the common naming convention for variables and
> parameters. I need to properly name a variable which can be a
> pathname or a stream or a function (closure). Is it
> pathname-stream-function or should it be pathname-or-stream-or-
> function? Can it be something shorter like path-designator (too
> vague/ misleading?)?
Vague is often an issue of documentation as much as expectation. Pick
something and use it consistently and it won't be vague for long. If
you aren't consistent throughout, that's where vague creeps in. Good
strong metaphors, used consistently, are fine. Words like "array" or
"stream" were certainly vague when first introduced, but with proper
documentation and consistent use, they quickly took on specialized
meaning.
I'd say definitely don't call it pathname-stream-function since that's
a naming style already used for other common things, and it sounds
like it will access the "stream function" of a "pathname", or perhaps
the "function" of a "pathname stream" (if there were such things).
A connective like "-or-" could help But though there is one major
negative: It sacrifices the easy ability to use it in sentences aloud
with the word "or" occurring free-standing in the sentence. Consider
reading aloud this sentence:
Should I use pathname-or-stream-or-function or alpha-or-beta-or-gamma?
All those or's sound like equals when read aloud, yet they are
structurally different.
As to making it be a something-designator, that's good, but begs the
question of what you're designating. What you describe sounds like no
particular designator defined by the system. You can extend the concept
to your own things, but you should make sure you do it consistently in
your code. Is a path a name you use a lot in a consistent way? If not,
focus on what the designated entity is called and then back up to what
can designate it.
Learn to use a thesaurus, too, if you get blocked, in order to seek
useful metaphor terms. The terms "destination", "sink", and "repository"
might be suitable for the thing you're trying to designate. Having a
number of ways to designate such an item and calling something that
does that a destination-designator might be good.
Hope that helps.
Trastabuga wrote:
> I am wondering what's the common naming convention for variables and
> parameters.
> I need to properly name a variable which can be a pathname or a stream
> or a function (closure).
> Is it pathname-stream-function or should it be pathname-or-stream-or-
> function?
> Can it be something shorter like path-designator (too vague/
> misleading?)?
For what its worth, I name variables based on their purpose, not based
on what type they hold. For example, (defvar account-number) may hold a
number, a string, or a structure of type 'my-system:account:number -- it
doesn't matter. What's important is that this variable's name tells the
reader what it should be used for. That said, I sometimes include type
information in variable names when localised code is translating back
and forth between two representations of the same information.
My 2 cents,
Daniel
D Herring <········@at.tentpost.dot.com> writes:
> For what its worth, I name variables based on their purpose, not
> based on what type they hold. For example, (defvar account-number)
> may hold a number, a string, or a structure of type
> 'my-system:account:number -- it doesn't matter. What's important is
> that this variable's name tells the reader what it should be used
> for. That said, I sometimes include type information in variable
> names when localised code is translating back and forth between two
> representations of the same information.
This is a bit afield, but NUMBER is a type in CL, and with a name like
that, somebody might expect to be able to compare the variable's value
with #'= or #'EQL, or to predict another account identifier via
arithmetic. If all you're promising is that the value uniquely
identifies some other datum or resource, IMO a name involving words
such as "identifier", "descriptor" or "handle" would seem better.
--
RmK
Richard M Kreuter wrote:
> D Herring <········@at.tentpost.dot.com> writes:
>
>> For what its worth, I name variables based on their purpose, not
>> based on what type they hold. For example, (defvar account-number)
>> may hold a number, a string, or a structure of type
>> 'my-system:account:number -- it doesn't matter. What's important is
>> that this variable's name tells the reader what it should be used
>> for. That said, I sometimes include type information in variable
>> names when localised code is translating back and forth between two
>> representations of the same information.
>
> This is a bit afield, but NUMBER is a type in CL, and with a name like
> that, somebody might expect to be able to compare the variable's value
> with #'= or #'EQL, or to predict another account identifier via
> arithmetic. If all you're promising is that the value uniquely
> identifies some other datum or resource, IMO a name involving words
> such as "identifier", "descriptor" or "handle" would seem better.
Good catch; that was a poorly considered example.
- DH
From: Kent M Pitman
Subject: Re: Need help in naming a variable
Date:
Message-ID: <uhcpghpcw.fsf@nhplace.com>
D Herring <········@at.tentpost.dot.com> writes:
> Trastabuga wrote:
> > I am wondering what's the common naming convention for variables
> > and parameters. I need to properly name a variable which can be a
> > pathname or a stream or a function (closure). Is it
> > pathname-stream-function or should it be pathname-or-stream-or-
> > function? Can it be something shorter like path-designator (too
> > vague/ misleading?)?
>
> For what its worth, I name variables based on their purpose, not based
> on what type they hold. For example, (defvar account-number) may hold
> a number, a string, or a structure of type 'my-system:account:number
> -- it doesn't matter. What's important is that this variable's name
> tells the reader what it should be used for. That said, I sometimes
> include type information in variable names when localised code is
> translating back and forth between two representations of the same
> information.
I agree. Though, to expand, I think this often depends on the nature
of the abstraction level that the function operates at, which is
orthogonal to the concrete nature of the data. For low-level utilities,
the abstraction level _is_ the data type. For high-level utilities, it
isn't. So since the OP didn't say, it's hard to advise how to weigh this
in other than that I think you're right to raise it as a contributing issue.
To be more concrete, the following two functions might do very similar
kinds of actions on very similar concrete data, and yet the names might
need to be very different:
(defun string-starts-with (string substring) ...)
(string-starts-with "John Doe" "John") => T
(defun same-first-name (person-full-name person-first-name) ...)
(same-first-name "John Doe" "John") => T
Yes, there are ways these two functions aren't operationally
equivalent, but that's my whole point--that the choice of name, to the
extent it matters at all, helps remind you of these facts. That's why
names matter.
Trastabuga wrote:
> I need to properly name a variable which can be a pathname or a stream
> or a function (closure).
> Is it pathname-stream-function or should it be pathname-or-stream-or-
> function?
> Can it be something shorter like path-designator (too vague/
> misleading?)?
What's the variable's purpose? If it has several implementations,
a good convention would be to name it after whatever it's used for.
--
Dan
www.prairienet.org/~dsb/
Trastabuga wrote:
> I am wondering what's the common naming convention for variables and
> parameters.
> I need to properly name a variable which can be a pathname or a stream
> or a function (closure).
> Is it pathname-stream-function or should it be pathname-or-stream-or-
> function?
> Can it be something shorter like path-designator (too vague/
> misleading?)?
>
> Thank you,
> Andrew
>
>
Depending on its actual use (and inferring from the choices you listed)
I might call it source or destination. Just a guess.
-- Jeff Barnett
(message (Hello 'Trastabuga)
(you :wrote :on '(Sat, 09 Jun 2007 07:08:32 -0700))
(
T> Can it be something shorter like path-designator (too vague/
T> misleading?)?
i it's too vague, pick one-two letter name, like f (file), s (stream), fd
(file descriptor) or whatever.
you can describe meaning in documentation or comment, but it won't bloat
code.
if it's parameter that describes where to write something to, why don't call
it "to" or "target"?
)
(With-best-regards '(Alex Mizrahi) :aka 'killer_storm)
"I am everything you want and I am everything you need")
Trastabuga <·········@gmail.com> writes:
> I am wondering what's the common naming convention for variables and
> parameters.
> I need to properly name a variable which can be a pathname or a stream
> or a function (closure).
> Is it pathname-stream-function or should it be pathname-or-stream-or-
> function?
> Can it be something shorter like path-designator (too vague/
> misleading?)?
Consider putting the type information into a
declaration. For example
CL-USER> (defun fetch-char (spigot)
(declare (type (or pathname stream function) spigot))
(typecase spigot
(stream (read-char spigot))
(function (funcall spigot))
(stream (error "Programmer ran out of time."))))
FETCH-CHAR
Then the human reader and the compiler will be singing from
the same song sheet, which should produce better harmony.
With appropriate compilation policy most implementations
will insert or omit checking code as you require.
Alan Crowe
Edinburgh
Scotland