variable names -- short or long?

[Strogian]

I used to like short variable names, but now I seem to be writing stuff like this:


word AutomaticDataSegmentNumber;
word InitialSize_Heap;
word InitialSize_Stack;
dword CS_IP;
dword SS_SP;
word NumEntries_SegmentTable;
word NumEntries_ModuleReferenceTable;
word Offset_SegmentTable;
word Offset_ResourceTable;
word Offset_ResidentNameTable;


I can't help but think it has something to do with me having read other people's code recently... :D

[flukshun]

i think length should be secondary to descriptiveness.

[blobaugh]

It all depends and what you are going to use in the variable depending on what type it is. Maybe you like one type better, but is using it going to get the job done

[Strike]

A variable's name should be precisely long enough to describe itself -- no shorter, no longer. Kind of like Abraham Lincoln is reported to have answered the question, "How long should a man's legs be?" with the answer "... long enough to reach the ground."

[Dark Ninja]

Yeah, I agree with the previous posts. However, please use some common sense. If you had to type:

String[] variableToHoldAnArrayOfStrings = new[] String;

a lot, you'd be asking for carpel tunnel.:p

[goon12]

I voted short, I agree with Strike's post, I feel that the name should be "short" as "long" as it is clear enough as to what it is. Does that make sense ? Rough night :D

[Strogian]

Yes, yes, good job -- you've all managed to reply without actually answering the question. This is a computer forum guys, not an English class. :D

Of course it should just be long enough to describe itself. But I'm just surprised at how long my names have been recently. What sorts of names do you guys use, that you feel describes stuff well?

AutomaticDataSegmentNumber
could be AutoDSegNum
or just AutoDS to be really concise

And that's not even going into capitalization-underscore stuff!

I would know what is meant by all of those. DS just means data segment, of course! But if someone is reading my code without having spent two days reading about a NE file format, they might wonder what that is supposed to mean. :D

The second one would probably do the job, but it isn't perfectly clear .. "I'm pretty sure that's for the automatic data segment, but I'm not really sure." I can tell you that there is no ambiguity with the first one. What is it? It's the automatic data segment number! You don't have to "decode" the name; just read it! ;)

I probably wouldn't make them this long in a short function or something, where you can just look two lines down and see what it is for. I guess I'm making these names longer because they match definitions _outside_ of the program. I'm reading a text file and I see, "The word at 1Ch specifies the segment number of the automatic data segment..." How much can I really compress that down without having to throw in a comment?

[sharth]

usually, i just pick the most identifyying word that describes it, and pick that... so... short?

[Strike]

Originally posted by Strogian
AutomaticDataSegmentNumber
could be AutoDSegNum
or just AutoDS to be really concise

I'd choose the first one. Maybe the second, but make it "AutoDataSegNum" or maybe just "AutoDataSeg" (if it's understood that that would mean "segment number"). The last one isn't concise, it's just terse :) Concise means "expressing much in few words" and that doesn't express much to me. It's all a judgement call depending upon what type of code you are writing, of course.

After all, what do you LOSE by having longer variable names anyway? It's not like it makes a difference in program execution time. So maybe it takes a few more seconds to type, big deal. A few more seconds of typing (even multiplied by typing it 50 times) is still better than spending 10 minutes trying to figure out what the hell a variable means.

[maccorin]

i like variable names like 'i'

chances are you know that's an iterator unless you've been living in a cave

EDIT:

for the above post

seg_num

[Strogian]

On the other hand, maybe it would be good to use short, abbreviated names, (like seg_num), and just put a comment next to it. That way, if I do a 'grep' for a certain word, it won't give me every usage of the variable -- just the one definition. (And then I can grep for that variable name if I want every usage.)

But then I would have to refer to the original definition to remember exactly what the data is supposed to mean.

Man, this is why I can never finish a program...

...unless I'm getting paid for it. Then I have to. :D

[bs_texas]

Originally posted by Strogian
How much can I really compress that down without having to throw in a comment?

Why would you not want to put comments in your code? Comments are an important part if you expect that other people will need to understand your code. Or even if you need to understand it later.
The more comments the better!!

In APL we used variables like A, B, C. It had to do with variable space reuse. (Although I don't now recall the details about that. But it made the programs more efficient and used less memory space.)
Then the comments spelled out what was happening.

Hey, but I do realize the need for descriptive variable names, however.

[maccorin]

Originally posted by bs_2003
In APL we used variables like A, B, C. It had to do with variable space reuse. (Although I don't now recall the details about that. But it made the programs more efficient and used less memory space.)


That is the dumbest thing i've ever heard in my entire life. If your worried about memory and efficiency you would be using a compiled language. If your using a compiled language the variable name means _nothing_ (to the compiler).

[maccorin]

Originally posted by bs_2003
Why would you not want to put comments in your code? Comments are an important part if you expect that other people will need to understand your code. Or even if you need to understand it later.
The more comments the better!!

Too many comments lead to unreadable code, just as no comments does.

If you have to comment on _what_ you are doing, you need to write new code.

[bs_texas]

Originally posted by maccorin
That is the dumbest thing i've ever heard in my entire life.

Cool... I'm glad I was able to help you achieve that. Hopefully some dumber stuff will come along for you.

:smilieface:
:winkysmilieface:
:tonquestickingoutsmilieface:
:rolleyessmilieface:

Ok, I take my vote back. :anotherwinkysmilieface:

How long have you been programming?
When did you start?
Just curious.

[maccorin]

Originally posted by bs_2003
Cool... I'm glad I was able to help you achieve that. Hopefully some dumber stuff will come along for you.

:smilieface:
:winkysmilieface:
:tonquestickingoutsmilieface:
:rolleyessmilieface:

Ok, I take my vote back. :anotherwinkysmilieface:

How long have you been programming?
When did you start?
Just curious.

I started when i was 10 w/ qbasic, hacked up gorillaz pretty bad, quit (i was 10... you know i had more interesting things to do ;p)

discovered linux in '97, never went back, shortly after (i'd say 3 days) i discovered gcc and started learning C, i've gone to school for Comp Sci and am currently finishing up a mathematics BS so i can go on to grad school.

all that said
I'm an opinionated arse, so don't take anything i say to seriously, you obviously have a sense of humor, so i probably like you.

[Ludootje]

Originally posted by maccorin
If you have to comment on _what_ you are doing, you need to write new code.
umm I'd say that's what most comments are for... Saying why or what you're doing. As long as you don't need to explain *how* you're doing it, I think your code's fine.
No?
(I could be wrong though, I don't know a ton about programming, and if there's one thing which isn't discussed during our coding classes, it's commenting. I think most of the class don't know how to do that yet, or what it's for)

[maccorin]

Originally posted by Ludootje
umm I'd say that's what most comments are for... Saying why or what you're doing. As long as you don't need to explain *how* you're doing it, I think your code's fine.
No?
(I could be wrong though, I don't know a ton about programming, and if there's one thing which isn't discussed during our coding classes, it's commenting. I think most of the class don't know how to do that yet, or what it's for)

generally i think comments should give insight onto the overall structure of a program and a functions place in it. Not what the function does, because if your using a decent name for it, and your code is clear, then that should be obvious.

for instance


/*
* make sure that prepare_monster is called before this
* function, they are broken into 2 because
* prepare_monster needs to do some setup whether or
* not there is someone to attack
*/
int monster_attack (entity_t *target, entity_t *monster)
{
some_code();
}


i guess what i'm trying to say is

/* this makes the monster attack */
is a _horrible_ comment, it adds nothing to the knowledge of the programmer and only wastes space

and i absolutely hate when i see code like this


#define TRUE 1
#define FALSE 2

// set Return value to true
int ReturnValue = TRUE;


that's just a waste of space, notice i used the CapsForEachWord syntax in naming there, because i've noticed that the same people that write redundant comments like that use that nameing scheme, i think it prolly comes from either java or M$

[bwkaz]

Besides, everybody knows that FALSE is 0! :p

[maccorin]

Originally posted by bwkaz
Besides, everybody knows that FALSE is 0! :p

i hate TRUE/FALSE anyways

0 for success -ERROR_NUM on error... that's all you need.

;p

[Ludootje]

Thanks for the explanations maccorin - I get your point better now :) (and agree with it, too)

Originally posted by maccorin
[Bthat's just a waste of space, notice i used the CapsForEachWord syntax in naming there, because i've noticed that the same people that write redundant comments like that use that nameing scheme, i think it prolly comes from either java or M$ [/B]
AFAIK it comes from Java.
I must admit I use camelCase too, though - it's just find it more readable.
What do you use? Underscores?

[bwkaz]

Originally posted by maccorin
0 for success -ERROR_NUM on error... that's all you need. Yep. It's even more descriptive in less "space" (space being number of variables required to figure out what the heck is wrong with your sendto(sock, buf, buf_len, flags, broadcast, bcast_len) call when sock doesn't have the SO_BROADCAST flag set).

Even glibc's syscalls returning 0 on success and -1 on error, with errno set to -<kernel return value>, is more things to look at than are necessary. But, we aren't going to be able to change it now...

[maccorin]

we aren't the only ones that think that, there was actually a post on LKML recently by linus where he expressed that he wished he could change standard conventions, because errno is horribly broken (due to it not being thread-safe)

[bwkaz]

Heh, I forgot about its thread-(un-)safety.

However, in <bits/errno.h> from glibc CVS 2004-01-03, there are some comments about errno being per-thread:

#ifdef _ERRNO_H /* comment from me: if included from errno.h */

/* ... */

# ifndef __ASSEMBLER__
/* Function to get address of global `errno' variable. */
extern int *__errno_location (void) __THROW __attribute__ ((__const__));

# if !defined _LIBC || defined _LIBC_REENTRANT
/* When using threads, errno is a per-thread value. */
# define errno (*__errno_location())
# endif
# endif /* !__ASSEMBLER__ */
#endif /* _ERRNO_H */ There is no #else for if __ASSEMBLER__ is not defined, though, so if it is defined, errno is not thread-safe. Same with _LIBC being defined or _LIBC_REENTRANT not being defined. So I think it's only OK from inside glibc's compilation maybe? I'm not at all sure when _LIBC is (and is not) defined...

[maccorin]

it looks to me like errno is thread safe _unless_ __ASSEMBLER__ is defined from that little bit. It's a bit different in kernel space (not using glibc....) so that's where i was getting that from.

Thanks for pointing that out. Useful to know.