www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Naming things: Phobos Programming Guidelines Propsal

reply Michel Fortin <michel.fortin michelf.com> writes:
It's interesting how the property debate is moving towards expressing 
semantics and how sometime the English language doesn't express things 
clearly -- empty (state) vs. empty (action) comes to mind.

Now that the debate is moving towards how to name things, perhaps it is 
time we establish a clear set of guidelines. Here's my attempt at it:
<http://prowiki.org/wiki4d/wiki.cgi?DProgrammingGuidelines>

It obviously lacks a few things, and doesn't fit half of today's Phobos 
very well. But I hope this document can bring some consistency to 
Phobos and other D projects. Feel free to discuss and improve the 
document as you see fit.

-- 
Michel Fortin
michel.fortin michelf.com
http://michelf.com/
Jul 29 2009
next sibling parent reply Ary Borenszweig <ary esperanto.org.ar> writes:
Michel Fortin wrote:

 It's interesting how the property debate is moving towards expressing 
 semantics and how sometime the English language doesn't express things 
 clearly -- empty (state) vs. empty (action) comes to mind.
 
 Now that the debate is moving towards how to name things, perhaps it is 
 time we establish a clear set of guidelines. Here's my attempt at it:
 <http://prowiki.org/wiki4d/wiki.cgi?DProgrammingGuidelines>
 
 It obviously lacks a few things, and doesn't fit half of today's Phobos 
 very well. But I hope this document can bring some consistency to Phobos 
 and other D projects. Feel free to discuss and improve the document as 
 you see fit.


There's a paradox. :-P

You say a class' name should be a noun. And you say a class' name 
shouldn't repeat it's base class name.

Say you have an Action class, very common in UI toolkits and things like 
that. Now you have an action to connect two things. Two alternatives:

1. class Connect : Action {} // wrong, Connect not a noun
2. class ConnectAction : Action {} // wrong, repeats Action
3. ...?
4. The universe expolodes.
Jul 29 2009
next sibling parent reply Michel Fortin <michel.fortin michelf.com> writes:
On 2009-07-29 10:53:59 -0400, Ary Borenszweig <ary esperanto.org.ar> said:


 Michel Fortin wrote:

 It's interesting how the property debate is moving towards expressing 
 semantics and how sometime the English language doesn't express things 
 clearly -- empty (state) vs. empty (action) comes to mind.
 
 Now that the debate is moving towards how to name things, perhaps it is 
 time we establish a clear set of guidelines. Here's my attempt at it:
 <http://prowiki.org/wiki4d/wiki.cgi?DProgrammingGuidelines>
 
 It obviously lacks a few things, and doesn't fit half of today's Phobos 
 very well. But I hope this document can bring some consistency to 
 Phobos and other D projects. Feel free to discuss and improve the 
 document as you see fit.


 
 There's a paradox. :-P
 
 You say a class' name should be a noun. And you say a class' name 
 shouldn't repeat it's base class name.
 
 Say you have an Action class, very common in UI toolkits and things 
 like that. Now you have an action to connect two things. Two 
 alternatives:
 
 1. class Connect : Action {} // wrong, Connect not a noun
 2. class ConnectAction : Action {} // wrong, repeats Action
 3. ...?
 4. The universe expolodes.


I'd go with "ConnectAction" to make sure there's a noun. The rule 
following the "don't repeat the base class name" one is aimed at 
allowing this specific usage. It says:

"""
It is fine to repeat the base type name in the derived type name if the 
derived type is only a specialization having the same function:

	class RemoteObject : Object { } // right
	class TcpSocket : Socket { }    // right
"""

Obviously it doesn't seem too well worded. Any alternative suggestion?


-- 
Michel Fortin
michel.fortin michelf.com
http://michelf.com/
Jul 29 2009
parent reply Ary Borenszweig <ary esperanto.org.ar> writes:
Michel Fortin wrote:

 On 2009-07-29 10:53:59 -0400, Ary Borenszweig <ary esperanto.org.ar> said:
 

 Michel Fortin wrote:

 It's interesting how the property debate is moving towards expressing 
 semantics and how sometime the English language doesn't express 
 things clearly -- empty (state) vs. empty (action) comes to mind.

 Now that the debate is moving towards how to name things, perhaps it 
 is time we establish a clear set of guidelines. Here's my attempt at it:
 <http://prowiki.org/wiki4d/wiki.cgi?DProgrammingGuidelines>

 It obviously lacks a few things, and doesn't fit half of today's 
 Phobos very well. But I hope this document can bring some consistency 
 to Phobos and other D projects. Feel free to discuss and improve the 
 document as you see fit.


 There's a paradox. :-P

 You say a class' name should be a noun. And you say a class' name 
 shouldn't repeat it's base class name.

 Say you have an Action class, very common in UI toolkits and things 
 like that. Now you have an action to connect two things. Two 
 alternatives:

 1. class Connect : Action {} // wrong, Connect not a noun
 2. class ConnectAction : Action {} // wrong, repeats Action
 3. ...?
 4. The universe expolodes.


 
 I'd go with "ConnectAction" to make sure there's a noun. The rule 
 following the "don't repeat the base class name" one is aimed at 
 allowing this specific usage. It says:
 
 """
 It is fine to repeat the base type name in the derived type name if the 
 derived type is only a specialization having the same function:
 
     class RemoteObject : Object { } // right
     class TcpSocket : Socket { }    // right
 """
 
 Obviously it doesn't seem too well worded. Any alternative suggestion?


I like it like that. It's a good rule. :)
Jul 29 2009
parent Michel Fortin <michel.fortin michelf.com> writes:
On 2009-07-29 11:24:18 -0400, Ary Borenszweig <ary esperanto.org.ar> said:


 Michel Fortin wrote:

 I'd go with "ConnectAction" to make sure there's a noun. The rule 
 following the "don't repeat the base class name" one is aimed at 
 allowing this specific usage. It says:
 
 """
 It is fine to repeat the base type name in the derived type name if the 
 derived type is only a specialization having the same function:
 
     class RemoteObject : Object { } // right
     class TcpSocket : Socket { }    // right
 """
 
 Obviously it doesn't seem too well worded. Any alternative suggestion?


 
 I like it like that. It's a good rule. :)


I added your ConnectAction example, this way there is an example with a 
verb in front of a noun.

-- 
Michel Fortin
michel.fortin michelf.com
http://michelf.com/
Jul 29 2009
prev sibling parent reply Chad J <chadjoan __spam.is.bad__gmail.com> writes:
Ary Borenszweig wrote:

 Michel Fortin wrote:

 It's interesting how the property debate is moving towards expressing
 semantics and how sometime the English language doesn't express things
 clearly -- empty (state) vs. empty (action) comes to mind.

 Now that the debate is moving towards how to name things, perhaps it
 is time we establish a clear set of guidelines. Here's my attempt at it:
 <http://prowiki.org/wiki4d/wiki.cgi?DProgrammingGuidelines>

 It obviously lacks a few things, and doesn't fit half of today's
 Phobos very well. But I hope this document can bring some consistency
 to Phobos and other D projects. Feel free to discuss and improve the
 document as you see fit.


 
 There's a paradox. :-P
 
 You say a class' name should be a noun. And you say a class' name
 shouldn't repeat it's base class name.
 
 Say you have an Action class, very common in UI toolkits and things like
 that. Now you have an action to connect two things. Two alternatives:
 
 1. class Connect : Action {} // wrong, Connect not a noun
 2. class ConnectAction : Action {} // wrong, repeats Action
 3. ...?
 4. The universe expolodes.


Why would there be a Connect class?

class Connection : Action {}

tada!  English words can often be nounized.
Jul 29 2009
parent Chad J <chadjoan __spam.is.bad__gmail.com> writes:
Chad J wrote:

 Ary Borenszweig wrote:

 1. class Connect : Action {} // wrong, Connect not a noun
 2. class ConnectAction : Action {} // wrong, repeats Action
 3. ...?
 4. The universe expolodes.


 
 Why would there be a Connect class?
 
 class Connection : Action {}


Nevermind that might not actually make sense.


 
 tada!  English words can often be nounized.


Sorry for the noise.
Jul 29 2009
prev sibling parent reply Jesse Phillips <jessekphillips+d gmail.com> writes:
I did some formatting for the page, and linked to the Style Guide. You should
note that by having a author field you are giving the impression that changes
should go through you.

Michel Fortin Wrote:


 It's interesting how the property debate is moving towards expressing 
 semantics and how sometime the English language doesn't express things 
 clearly -- empty (state) vs. empty (action) comes to mind.
 
 Now that the debate is moving towards how to name things, perhaps it is 
 time we establish a clear set of guidelines. Here's my attempt at it:
 <http://prowiki.org/wiki4d/wiki.cgi?DProgrammingGuidelines>
 
 It obviously lacks a few things, and doesn't fit half of today's Phobos 
 very well. But I hope this document can bring some consistency to 
 Phobos and other D projects. Feel free to discuss and improve the 
 document as you see fit.
 
 -- 
 Michel Fortin
 michel.fortin michelf.com
 http://michelf.com/
Jul 29 2009
parent Michel Fortin <michel.fortin michelf.com> writes:
On 2009-07-29 13:46:46 -0400, Jesse Phillips <jessekphillips+d gmail.com> said:


 I did some formatting for the page, and linked to the Style Guide.


Good idea. I think eventually, if the guidelines actually get some 
attention, both documents should be merged. They're essentially two 
sides of the same coin.


 You should note that by having a author field you are giving the 
 impression that changes should go through you.


Ah, well. That's not my intent, otherwise I wouldn't have posted this 
on a wiki. Fixed.

-- 
Michel Fortin
michel.fortin michelf.com
http://michelf.com/
Jul 29 2009