What are your studios code naming conventions and why?

Questions
#1

When I am reading other peoples codes:

Some are almost like reading regular English. Consistent and intuitive names.
Such as Main_Menu, Player_Shield, Background_Image, Options_Gui_Container etc

Others read like a 1950’s military engineering manual with zero names- just combinations of characters and digits and reused in local but in different ways and for different purposes. But with deliberate obfuscation of variable meanings. This was to reduce memory, make the code harder to hack, and make it unintelligible to their bosses for job security. (yes I was a nuclear machinist mate in the US Navy in my early 20’s. )

Where as example I had been issued in boot camp a “w639b6- self composting, spatially distributed cellulose fibrous structure, with resin impacted optical identification, vegetable resin enhanced structural walls and base, performing fluidic medium contained transportation system maximized for optical fluid consumption and co engineered for small groupings or singular solid medium object containment and transportation- category 1(b)” - or in English a drinking cup)

Some developers have that mind set: refusing any human readability and reusing same variables such i,ii, b23r, aaa, and with zero commenting on what those variables mean or what the function is supposed to do.

I was reading a script the other day- that I had written years ago in python. I had no idea what my variables meant or even what they did. I mean I know they were in a loop, or they were calculating math or something but it took me a long time to go back and discover the cryptic meaning of “id<zw[0]” when zw[0] =jj and what that had to do with c_id.

yesterday I was reading a script on creating a menu in defold. And in every script in the project it was human readable- until this one script where every variable was a single local variable- i or j. In every function in the script and there had to have been over 200 lines. With no rationale way of telling how any of them tied together. No single comment, and not a single variable that even hinted at what was being done.

This kind of thing will make your future self hate your present self. When you have to maintain this project and havent seen this script in a year or more you won’t remember what i or j or z_1 means and you will have to become a detective and waste time reverse engineering you code to find the one line out possible thousands that needs to be changed to affect the variable i.

Or worse the dev just copied dozens of snippets hodge podge into a script- with no understanding what the variables meant- just that they worked in somebody else’s project. And now they want you to fix it. in there :wink: (Nooo I have NEVER done that!)

On the other hand I ending up reading another script that “BOOM” it was legible concise and human readable. Working on that guys team would be much less frustrating than say Govt Bob’s cryptic code.

So what kind of system do you use and do other people like it?

1 Like
#2

Nowadays, compilers are much smarter and also computers have more registers, thus allowing you to have more variable names.

That said, having clear names is always preferred. However, what constitutes a “clear” name is of course subjective.

When it comes to looping variables, we often lend from math notation, and use i, j, k etc. It’s usually not a problem, but if the scope grows too much, it might not fit very well anymore.

In general, my (very generic) advice is to keep functions short and to the point. E.g. a function only does one thing, and does that well. That often makes them much more readable from the start. And together with a good function name it should also help read the code inside the function.

All code I write will look “old” after a while, but hopefully I can at least read it to understand what I meant with it. If I still have trouble with it, it’s usually down to the complexity of the function/system itself.

4 Likes
#3

Of course- if the function purpose and meaning is clear then using single letter variable is fine. A simple comment would fix that.

And of course when I first started I bought new programs in magazines like “BASIC” and typed them into a computer and saved them on a cassette tape. Sometimes they were in Assembly.

So moving into basic and single letter variable were a big step above than two magazine pages of numbers praying to God you didnt mistype a 1 for a 0!

For me its because I was taught to use j and I in for next loops almost 40 years ago and I HAVE to consciously use words instead. So many times I stull use the i or j and add a comment above function.

Does your team have a naming convention bible yall conform to or is everybody doing just what works best for them?

1 Like
#4

For our gamedev team with Lua, we use snake_case for nearly everything except for constants which are all CAPITALIZED.

For other languages, like with native extensions, we generally try to match the existing style pattern of that language except to the point of going to the Lua side (such as with native extensions).

We favor descriptive names rather than cryptic ones meant to save space. And generally we’ll spell out iterators too. There are exceptions for us like k,v kk,vv etc. for loops of key/value loops of tables as a pattern that is obvious.

Usually I think people who use those one letter variables are either used to trying to be efficient, don’t feel the need to change legacy from older languages like Fortran, or have a math background where to them the letters are intuitive. For looping I’m fine with short letters but for math I feel things should be more spelled out even if it requires more typing. Of course it depends if you are ever going to work with others if you want to spell things out beyond what you like or not.

We are strongly against “clever” code unless there is a good reason for it. Everything should be understandable to be read without comments generally. Comments can still be used for things like noting pitfalls or for setting up documentation.

This is the sort of thing I would avoid with Lua even if it’s allowed.

(print or io.write)('done')

We also do local module = require("module") instead of local module = require module because to me it’s more correct to include the () even if you don’t have to.

Lua has features like ; but even though it can be used please don’t use it ever unless you have a real reason to.

Write the way that is intuitive to you that you know future you will appreciate. Reading existing Lua code from popular projects is a good idea to do for a sense of coding style. Anything by @britzl is a good reference https://github.com/britzl (and of course if you contributed to his projects you would want to match his coding style).

The Monarch module for example has most of the styling you may want to observe for good practices.

https://github.com/britzl/monarch/blob/master/monarch/monarch.lua

There are always exceptions. What matters about style is what you and your current or future team are comfortable with / how compatible you want your code to be stylistically with other existing public projects.

6 Likes
#5

That is a great commentary!

1 Like
#6

I just read the monarch lua file and it is easy to read and follow. Thanks for sharing it.

1 Like
#7

As long as you use tabs, not spaces, almost every other coding-convention sin can be forgiven. Not spaces. Spaces (for indentation) can never be forgiven!!!

[Edit] I forgot to add exclamation points! :stuck_out_tongue:

I’ve been getting better at naming things. Generally I use shorter names for smaller contexts, and vice versa, erring on the side of longer names.

I often use aliases within a small context so that things take up less space when I actually use them, and to allow myself to use longer names than I might otherwise. Inside a callback I might have:

local accel = config.playerLinAccel
or:
local s = self.flashSprite

Of course if you have things like this:

local btn = self.invMenu.buttons[1]

…it can also save performance, since you’re not repeating three table-accesses every time you use it. Sometimes I see code that repeatedly gets the same thing from inside nested tables, multiple times on the same line…nope.

Often, trying to read code as if it’s regular speech can help come up with better names. I started prefixing my boolean variables with “is” for this reason.

if polygon.isLooping then reads a little better than: if polygon.loop then

And rather than 'loop', it’s pretty clear that 'isLooping' is not some reference to a list of polygons that happen to be arranged in a loop…or something. You can do the same thing for function names—read out the code where you use it, and try to make it sound sensible.

String/Hash/Number IDs or names of things generally get “name”, “ID”, “index”, or at least “I” appended to them, making it clear that “roomName” or “roomI” is not a reference to the “room” (or possibly “roomObj”) itself.

I guess these last two points fall into the category: adding some Type indication to your names. I’m not a fan of adding a one-letter type prefix to everything though (it seems weird in Lua anyway).

Possibly one of the more questionable things I do is condense short blocks into a single line, but separate them with double spaces (wait…spaces?).

if enabled then  button:enable()  end
-- instead of:
if enabled then
	button:enable()
end
-- or, more rarely:
for i,v in ipairs(t1) do  t2[i] = v  end

-- Especially when there's multiple blocks in a row.
-- I'll definitely take this:
if data.sensor then  fixt:setSensor(data.sensor)  end
if data.friction then  fixt:setFriction(data.friction)  end
if data.restitution then  fixt:setRestitution(data.restitution)  end
-- over the -9- lines it would otherwise take.
-- (Three known items doesn't warrant a loop.)

Multiple related variables (like x, y, z) can get set in one line to save space, but I try not to do that just to save space, if the variables aren’t very closely related.

-- It's a bit of a toss-up, but I prefer this:
x, y = x + vx*dt, y + vy*dt
-- over this:
x = x + vx*dt;  y = y + vy*dt
x = x + vx*dt  y = y + vy*dt -- (or without the semicolon separator)
-- because then I can quickly see that I'm setting all the variables before the =.

-- Yes...sometimes I remove the spaces around * and / if I think it improves readability.

I’ve never actually done it myself, but using spaces in the middle or at the end of lines to align things vertically is kind of cool: https://github.com/rxi/flux/blob/master/flux.lua
It certainly looks pretty fancy!

P.S. Regarding indentation. 2 spaces is obviously too short, but 4 spaces…might be slightly longer than necessary for readability, so I actually use: 3 spaces!
…but of course I use tabs, so no one will ever know…

3 Likes
#8

Sweet breakdown!

1 Like
#9

Grabbing popcorn!

This is a good recommendation. It really helps to follow the conventions of the language itself. Or the conventions of the library/framework you are using.

6 Likes