Good Variable Names

[Akaya]

Was having some trouble with variable names getting really long. Came across this guideline. Do you agree or disagree with it?

http://c2.com/cgi/wiki?GoodVariableNames

[Oneymus]

I firmly agree with the argument that code should be written for future readers. Numerous studies prove that code is read more than it is written; this can be seen even in the act of sharing scripts here. Therefore, I do believe that variable name need to be descriptive.

Descriptive names aren't necessarily long names, though longer names are often more descriptive than short names. My eyes were opened after reading Steve McConnell's Code Complete. I highly recommend it.

Sad to say I read this long after releasing Vyzor, so it's not a great example. It's inconsistent and sometimes very confusing.

[demonnic]

I tend to agree with the concept that variable names should be descriptive and that code should be written as to document itself whenever possible. I obviously don't always maintain that standard, but I rarely use very simple variable names unless it's very obvious what is happening, and often then I'll still using something more descriptive. It makes it easier on me to write the code, let alone read it.

Code: [show] | [select all] lua

for idNumber, name in pairs(roomItems) do
  echo("ID#:" .. idNumber .." is named " .. name .."!\n")
end

can be difficult enough for some beginners to make sense of if they're completely fresh to scripting. And keeping track of what k and v are can be arduous even for people who've been doing it awhile. Sure, you can save a few keystrokes, but when you have to come back and fix a bug in a year or so, it may not be so obvious what k[k2[v]] is meant to be referring to.

[Vadi]

Definitely use descriptive names over short ones. A good editor will help you not having to type them out these days. I came across this on my own, giving variables good names so you can just "read" the code is
nice.

[Akaya]

Do you have techniques for condensing your names?

Also, camelCase vs. under_score. Are there certain instances in which one is better than the other?

[Vadi]

I like Lua's variable naming convention. Ends up being lowercase all the time, words concatenated together most of the time, underscore when necessary.

[demonnic]

This is one of those cases where if you got twenty developers in a room and asked them what good code looks like, in terms of style, variable naming, etc. And you'll get fifty answers, of which you could perhaps argue them down to ten 'standards' that most of them could agree maybe didn't suck so bad if you're having to make compromises to work with others.

And they'd still randomly shift between them depending on their mood (or for some the planetary alignments it seems).

That may be a tiny bit exaggerated, to be fair, but even just viewing the original link you can tell there's plenty of debate.

And yeah, my code can be all over the place sometimes.

[Akaya]

So I took these tips to heart and wrote the Achaea Calendar with it. It's very easy to read. Check it out if you want.

The quality of my code improved so much (in my opinion) that I continued research on this topic...

The term 'Lua's variable naming convention' was an interesting one. So I turned to Google and found a very helpful page: http://lua-users.org/wiki/LuaStyleGuide

It mentions Steve McConnell's Code Complete (which I skimmed through and I really think I'll take the time to sit down and actually read) as good reference

A few good tips I'll carry on were:
1) Prefixing booleans with 'is'. Never thought of this. Great idea.
2) Using camelCase for user-defined variables. Not sure if I'll adapt to this one or not, but a good plan none-the-less.
3) Using an underscore as a placeholder. This is something I've seen a lot but never really caught on. Definitely going to utilize this one.
4) When commenting, placing a space after --. I've always been on the fence about whether or not to do this. Not a big deal, but I'll stick with the suggested way
5) Commenting the 'end' of your blocks. Again, I've seen this done and the benefit is very clear with large blocks. Probably unnecessary for smaller ones.

[demonnic]

For number 5, do you mean placing a comment at the 'end' statement noting what block it's the 'end' of? I sometimes do this, but I was never sure if it was annoying for others or not.

[Akaya]

Yes. Such as...

Code: [show] | [select all] lua

 if some_variable then
  for k,v in pairs(t) do
     if type(v) == "string" then
       dostuff()
    end -- if
  end -- for
end -- if

I believe I've seen this in your code. Good practice