(Rant) Use descriptive variable names!

Unity Courses Talk
,
#1

I know this is nit-picky, but using the variable name man for a LevelManager is just plain a bad idea. Sure, the scope is extremely limited, but there’s no reason to name variables so that they obfuscate their meaning.

As this is a course for learning, best practices should be shining through. From the very beginning, developers should be naming everything as best they can. Code is read more than it’s written, and nobody likes writing documentation, so write self documenting code! “Man” is a word that has meaning, and when I read man.LoadLevel() I think “who is this man, and why is he loading levels in my space game?”. If you want more terse code, consider naming the method load, as it should be reasonably clear that a (well named) LevelManager would be loading levels - levelManager.load("level") vs man.loadLevel("level").

IDEs do all the work anyways, you don’t even have to type the variable names out after the first time!

#2

Hi there, I actually agree with you. Manager is a bad name, and when we re-work this course we’ll use a different name.

Oh well, the course is finished, not perfect.

Thanks for the feedback

Ben

#3

This is a misconception of many coders, surprisingly even professionals that you can somehow replace documentation with good naming.

Sorry but … nope !

Code can never come even close as a light year to conveying even half the information that documentation can. That’s is just the reality of it.

As a matter of fact you can understand code fine even with the worst name in the history of coding if it comes with good documentation.

You will never be able to understand any quite of large coding project just by reading the code unless you are willing to close yourself in a room and not get out for months if not years. Documentation will help you understand it in days at most weeks.

No programming language was ever made to represent abstract concepts.A programming language may have “language” in its description but as languages go is extremely limited one. Actually programming languages really suck at it.

Programming languages not only are extremely limited in describing the what and the how, but they are completely incapable of explaining the why which what makes comments mandatory to every single line of code. But because having a ton of comments is not pretty, you fall back tooooo…yeap… documentation.

Sure if you write a simple main() you don’t need it, if you make a simple function you dont need but in the real word 99% of the time you will need it. Actually you need it so much that coding nowdays has far more mediums of expressions than programming in form of wikis, references, tutorials, QAs , forums, live chat and much more. The only form of expression for programming is the programming language, the end.

The problem becomes bigger with legacy code that tends to be nothing more than a collection of badly designed patches. Good designs need time, coders rarely have the time to do that because bosses or they want features. Code grows bigger and bigger and more and more ugly. Good naming provides zero help because everything is spaggetified and documentation is your only salvation because a rewrite aint gonna happen any time soon.

So yes please do use good names, totally agree, but no definitely not do it to avoid writing documentation and by documentation I dont mean 2 lines comments. The bigger the project the bigger its reliance on good documentation.

And no you cannot use unit testing for replacing documentation either. No way around it. Either you document or your code sucks big time because people wont even bother reading it. Even with the best naming in the world. Plus if you start reading your own code years after you probably gonna ask yourself what the hell you were thinking when you were writing the code.

1 Like
#4

By no means did I mean to condemn the course on that single variable name. So far (I’m just starting Glitch Garden) I’ve loved the course, and particularly with respect to value for money I think it’s amazing. Makes me cringe thinking how much I spent on university courses that weren’t anywhere near this quality… The reach of the course is what motivated me to comment in the first place - this is an awesome entry into software for what appears to be thousands of people. You guys have a real opportunity to instill good practices, which you mention many times with the design decisions in the programs themselves, so in my mind it makes sense to keep that quality all the way down to the small things.

I fundamentally disagree with you there. Well named functions and variables and classes CAN completely displace the need for some parts of the documentation.

Completely agree with you there. Good names does not mean no documentation needed.

These are two VERY different concepts. Documentation for an end user (e.g. that of a library or an API) has massive benefits. For methods buried layers deep code no one will ever look at except the developers, documentation is often more of a liability than anything else - now you don’t need to just read the code, you need to maintain the documentation as well.

This is completely out of touch with modern industrial software development best practices. I would contend that you’re actually backwards here - the vast majority of functions are self descriptive if written well. If 99% of the time you’re writing methods that need documentation to be understood by a reasonable reader, you’re doing something terribly wrong. Many small, simple, well named functions combined into well formed classes can absolutely displace documentation, with the perk that the code never gets out of sync with what’s happening whereas the documentation absolutely does on any sufficiently large project.

All told, I think we agree that there is no net benefit to poor naming and there is value in good naming. I’d be thrilled if everyone in the world documented their code thoroughly, it’s just never going to come even close to happening.

#5

Here is a good book regarding coding standards Clean Code: A handbook of Agile Software Craftmanship Author Robert C. Martin
The book is Java based but the concepts cover OOP programming I recommend this to all of our junior developers.

1 Like
#6

I completely agree, I have it thanks to @sampattuzzi buying it for my 40th birthday and once I have read it I’ll recommend it as appropriate in the courses.

#7

BTW, why use

LevelManager man = GameObject.Find("LevelManager").GetComponent<LevelManager>(); man.LoadLevel("Win Screen");

instead of

?

Creating a new LevelManager object just for the sake of calling the LoadLevel method in the line after seems like a waste of time and memory.

#8

I think you’re misunderstanding what this code is doing a little. To illustrate, consider:

// Instantiate an object, but don't keep a reference to it
new Object();

and

// Instantiate an object AND keep a local reference to it
Object object = new Object();

Both these examples do the same amount of work - the instantiation of the Object is far and above the most taxing in terms of time and memory. Both examples mean a new Object is created, allocated some space in memory, and eventually will need to be garbage collected. Storing the reference (Object object = ...) is free1, the object is created and later destroyed regardless.

In your example, GameObject.Find("LevelManager").GetComponent<LevelManager>() it’s chaining a bunch of method calls, but each is executed the same. First GameObject.Find("LevelManager") is creating a GameObject, then GetComponent<LevelManager> is creating a LevelManager. Those objects are created/fetched regardless. So performance wise, it’d be equivalent to doing:

GameObject levelManagerGameObject = GameObject.Find("LevelManager");
LevelManager levelManager = levelManagerGameObject.GetComponent<LevelManager>();

So you don’t save any time or memory by not assigning it to a local variable. It’s just a decision as to whether it’s more readable or not at that point. From that perspective, maybe it’s a point in your favor that you avoid an opportunity for bad variable naming…

1Storing a reference isn’t literally free, after all the reference needs to sit somewhere and it’s lifetime has to be considered by the garbage collector, but it’s so close to being free that it’d almost always be a mistake to write code explicitly to avoid local variables. Virtually every other concern is more important - including code readability - for the overwhelming majority of software.

1 Like
#9

What bothers me most is that, as a beginner, you get stuck in situations like this where they just added variables without telling anyone. Sure it is fun to look up and try to solve the problem yourself, especially when doing the lessons in Unity 5. But it is annoying because the last 3 or 4 times I got stuck is because you randomly decided to change variable names.

#10

Thanks for this feedback, I can’t pass it onto Brice as he is no longer with us, but this is noted and we do try hard to use descriptive and consistent names in our recent content. Thanks for speaking up on this!

#11

Thanks for the reference. The issue of quick and dirty stream-of-consciousness coding drives me absolutely nuts.

Privacy & Terms