Re: Lua 5.1 (alpha): Documentation "bug" and suggestions

[Philippe Lhoste <PhiLho@...>]

steffenj wrote:
> I would like to see all the functions updated to also show the return
> values. You always have to pick them out of the description text that
> follows (if there is any hint, for example, getfenv doesn't explicitly
> mention that it returns a table).

Good point.

> Also, i personally feel that it is often confusing not to know what type of
> value we're dealing with here. I wonder if this never occured to anyone
> before because almost all scripts i look at don't follow any variable naming
> convention at all. A variable "index" could be an integer, a string, or even
> a table. This isn't clear without looking at the context, and that makes
> reading (especially complex) scripts harder than it need be.
>
> I've come up with a simple scheme for naming my variables which i've sticked
> to for like 50.000 lines of Lua code:
>
> nNumber = 123
> 	iInteger = 123 or rReal = 1.23 to differentiate where needed
> sString = "a string"
> bBoolean = true
> tTable = {}
> uUserdata = <someuserdata>
> fFunction = function f() end
> cCoroutine = co
> hThread = <thread>
> xUnknown (for values whose type is determined at runtime, eg a table index
> can be both a string and an integer when walking through table elements)

Aha, this has a strong flavor of the quite controversed, (in)famous 
Hungarian notation...

Actually, in most of my programs (C/C++/Java/Basic/Lua/PHP/whatsnot), I 
try to stick to a subset of this notation -- mostly a for arrays, b for 
boolean because I allow the 'if bTest then' only on booleans, even in C, 
m for malloced data (to remember to free it), etc.

Of course, one may argue than in a weakly typed language, these 
notations are meaningless. Counter-argument: it is bad practice to reuse 
variable names for something totally different...

> An additional prefix "g" to mark global variables (visible even across
> files). So that would make: gnGlobalNumber etc.

For such rules (scope, static, etc.), I prefer to use g_, s_, gs_... to 
separate from type.

> Giving variables reasonable names (and prefixed) seems to be neglected far
> too often in the Lua community, if i may say so. I often find it hard to
> read scripts as i have to keep in mind one extra information about each
> variable: it's type. If i can't remember, I'll have to go back and scan
> through the relevant parts again, eg looking up the type of value a function
> returns. And then back again to where i was. ... Where was I? <sigh>
>
> Sure, it's quicker to write everything in lowercase letters and stick to
> variable names with at max 6 chars. Sure, it's hard to stick or even get
> used to naming conventions when many Lua scripts are at most 200 lines. Yes,
> i *felt* that, too. But it would still make it easier to understand the
> scripts, even for the scripter (my personal experience tells me so). 

I agree :-) But C programmers seems to have a strong incline for small, 
abbreviated and unreadable names :-P
I dropped this practice quite a long time ago (except for i, j, k...) or 
when I feel lazy on very short-lived variables or on very small programs.

--
Philippe Lhoste
--  (near) Paris -- France
--  http://Phi.Lho.free.fr
--  --  --  --  --  --  --  --  --  --  --  --  --  --