www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Readability and naming.

reply Mike Gerfin <gerfin ieee.org> writes:
I came to this site following the link from Dr. Dobb's and love
what I see.  I can't wait to start implementing my next project
in D!  However, on the subject of readability and D's promise
(or goal) to make things easier for other programmers, I wish
that C/C++ programmers would eliminate their attachment with
needlessly terse variable and function names.  Granted, I've
only been going through the site a few hours, but in many examples
I see things like:

int w_count, l_count;   // etc.

Why can't we use:

int wordCount, lineCount;

I realize these are just examples, but if people get used to
seeing descriptive naming used it will hopefully become the norm.
Let's not persist with habits born from the days of FORTRAN.

My 2 cents.

-Mike
Jan 10 2007
next sibling parent reply Sean Kelly <sean f4.ca> writes:
Mike Gerfin wrote:

 I came to this site following the link from Dr. Dobb's and love
 what I see.  I can't wait to start implementing my next project
 in D!  However, on the subject of readability and D's promise
 (or goal) to make things easier for other programmers, I wish
 that C/C++ programmers would eliminate their attachment with
 needlessly terse variable and function names.  Granted, I've
 only been going through the site a few hours, but in many examples
 I see things like:
 
 int w_count, l_count;   // etc.
 
 Why can't we use:
 
 int wordCount, lineCount;
 
 I realize these are just examples, but if people get used to
 seeing descriptive naming used it will hopefully become the norm.
 Let's not persist with habits born from the days of FORTRAN.


Personally, I think variable names should be clearly understandable to a 
code reviewer, but this doesn't always equate to long names.  I feel 
that scope, for example, plays a large part in what represents a 
meaningful name.  Local variables inside a small function are just fine 
at one or a few letters, and this may actually improve code readability 
by keeping algorithms compact.  However, the broader the scope is, the 
longer the names tend to become, in an attempt to provide contextual 
information.


Sean
Jan 10 2007
next sibling parent reply Steve Horne <stephenwantshornenospam100 aol.com> writes:
On Wed, 10 Jan 2007 14:34:59 -0800, Sean Kelly <sean f4.ca> wrote:


Personally, I think variable names should be clearly understandable to a 
code reviewer, but this doesn't always equate to long names.


Agreed. The way some people go on about long names, I suspect they
write code along the following lines...

  int
local_variable_for_the_total_of_all_items_from_an_array_of_arbitrary_values
= 0;

  for (int
local_variable_holding_loop_index_counting_through_array_subscripts =
0; local_variable_holding_loop_index_counting_through_array_subscripts
< parameter_holding_an_array_of_arbitrary_numeric_values.length ();
local_variable_holding_loop_index_counting_through_array_subscripts++)
  {

local_variable_for_the_total_of_all_items_from_an_array_of_arbitrary_values
+= parameter_holding_an_array_of_arbitrary_numeric_values
[local_variable_holding_loop_index_counting_through_array_subscripts];
  }


Wow, that's just so amazingly readable, what with those long
identifier names!

-- 
Remove 'wants' and 'nospam' from e-mail.
Jan 10 2007
next sibling parent Lutger <lutger.blijdestijn gmail.com> writes:
Steve Horne wrote:

 On Wed, 10 Jan 2007 14:34:59 -0800, Sean Kelly <sean f4.ca> wrote:
 

 Personally, I think variable names should be clearly understandable to a 
 code reviewer, but this doesn't always equate to long names.


 
 Agreed. The way some people go on about long names, I suspect they
 write code along the following lines...
 


<funny code>

Haha, that reminds me of some Java code I sometimes see. However I agree 
with the OP on this one:

     w_count vs wordCount

It's only two more characters and the '_' is more annoying to type. I 
find variable names consisting only of alphabetic characters better to 
read too.

But YMMV of course. I'm just glad D is not as verbose as Java.
Jan 11 2007
prev sibling parent reply Mike Gerfin <gerfin ieee.org> writes:
== Quote from Steve Horne (stephenwantshornenospam100 aol.com)'s article

 On Wed, 10 Jan 2007 14:34:59 -0800, Sean Kelly <sean f4.ca> wrote:

Personally, I think variable names should be clearly understandable to a
code reviewer, but this doesn't always equate to long names.


 Agreed. The way some people go on about long names, I suspect they
 write code along the following lines...
   int
 local_variable_for_the_total_of_all_items_from_an_array_of_arbitrary_values
 = 0;
   for (int
 local_variable_holding_loop_index_counting_through_array_subscripts =
 0; local_variable_holding_loop_index_counting_through_array_subscripts
 < parameter_holding_an_array_of_arbitrary_numeric_values.length ();
 local_variable_holding_loop_index_counting_through_array_subscripts++)
   {
 local_variable_for_the_total_of_all_items_from_an_array_of_arbitrary_values
 += parameter_holding_an_array_of_arbitrary_numeric_values
 [local_variable_holding_loop_index_counting_through_array_subscripts];
   }
 Wow, that's just so amazingly readable, what with those long
 identifier names!


Haha, nice.  I'll agree, naming can be abused in both directions.
Jan 11 2007
parent Steve Horne <stephenwantshornenospam100 aol.com> writes:
On Thu, 11 Jan 2007 16:25:41 +0000 (UTC), Mike Gerfin
<gerfin ieee.org> wrote:


Haha, nice.  I'll agree, naming can be abused in both directions.


Yeah - the real pain, though, is that there is no clear rule for where
the happy medium is. This is one debate that's never going to end,
basically, and 90% of the time you'll find that the people arguing
each side aren't really so far different as they think.

On the w_count vs. l_count, for me, it's a grey area. It depends on
the context. Abbreviating the differing part (word vs. line) seems odd
when you have the 'count' bit specified in full, but that depends on
context too. If you have lots of variables relating to words and
lines, and these are the only two that hold counts, it makes sense.
Also, how long should a sane and non-compulsive developer spend
analysing whether he's chosen the exact right identifier names?

Of course my reaction here is mainly a kneejerk thing - I've read too
many style guides in my time, and react badly to anything that hints
at a 'one true style' approach, even when that isn't what people are
really hinting at. It's kind of a Pavlovian thing I suppose.

As for underscores, though, you're all just so horribly wrong.
Underscores are lovely. Everyone should use underscores ;-)

-- 
Remove 'wants' and 'nospam' from e-mail.
Jan 11 2007
prev sibling parent =?UTF-8?B?THXDrXMgTWFycXVlcw==?= <luismarques gmail.com> writes:
Sean Kelly wrote:

 Personally, I think variable names should be clearly understandable to a 
 code reviewer, but this doesn't always equate to long names.  I feel 
 that scope, for example, plays a large part in what represents a 
 meaningful name.  Local variables inside a small function are just fine 
 at one or a few letters, and this may actually improve code readability 
 by keeping algorithms compact.  However, the broader the scope is, the 
 longer the names tend to become, in an attempt to provide contextual 
 information.


I agree with Sean here. Still, I advise you to err on the side of making 
it longer. First, because we are already a bit too biased for making it 
terse (those having a C, FORTRAN, etc background). Second because, being 
your own code, you'll tend to make optimistic assumptions about its 
readability. I had that experience recently: I was unsure about the best 
trade off in a particular module, but ended up choosing abbreviated 
versions of some variables. Two weeks later, when I had to read my own 
code, I found the full names were more clear, because I no longer 
remembered all the details which had biased me when I wrote it ("of 
course I'll understand that!").

Also, I think the following is an unneeded assault on elegance:

from: http://www.digitalmars.com/d/

"class CmdLin"

CmdLine is not that longer to write. This is *the* sample D code, on the 
language's frontpage. Perhaps some will find "CommandLine" too long, but 
surely CmdLine is quite reasonable.

Best regards,
Luís
Jan 11 2007
prev sibling parent reply Kyle Furlong <kylefurlong gmail.com> writes:
Mike Gerfin wrote:

 I came to this site following the link from Dr. Dobb's and love
 what I see.  I can't wait to start implementing my next project
 in D!  However, on the subject of readability and D's promise
 (or goal) to make things easier for other programmers, I wish
 that C/C++ programmers would eliminate their attachment with
 needlessly terse variable and function names.  Granted, I've
 only been going through the site a few hours, but in many examples
 I see things like:
 
 int w_count, l_count;   // etc.
 
 Why can't we use:
 
 int wordCount, lineCount;
 
 I realize these are just examples, but if people get used to
 seeing descriptive naming used it will hopefully become the norm.
 Let's not persist with habits born from the days of FORTRAN.
 
 My 2 cents.
 
 -Mike


Welcome to D! I'm curious if you have specific plans for what you are 
writing in D?
Jan 10 2007
parent Mike Gerfin <gerfin ieee.org> writes:
== Quote from Kyle Furlong (kylefurlong gmail.com)'s article

 Mike Gerfin wrote:

 I came to this site following the link from Dr. Dobb's and love
 what I see.  I can't wait to start implementing my next project
 in D!





 Welcome to D! I'm curious if you have specific plans for what you are
 writing in D?


I have many areas where it could be used, but it especially meets
my needs for image manipulation.  I do a lot with image processing
and analysis, a place where managing memory and pointers can be a
huge hassle.  But it is still nice to have that facility available
when advance things become necessary.  I'm also a fan of D's
numerical capabilities.

From a project standpoint, I love the ability to add unit tests
that are automatically run.  Great feature to have.
Jan 11 2007