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...

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.

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