What is readable code? What are the best practices to follow while naming variables?

Question

Do you think x, y, z are good variable names? How will you explain a new programmer to write readable code?

Answer 1

Certainly there are multiple schools of thought on this, but I would only use these for counters, and advise far more descriptive names for any other variables.

Answer 2

x, y and z can be perfectly good variable names. For example you might be writing code that refers to them in reference to a 3D cartesian coordinate system. These names are often used for the three axes in such a system and as such they would be well suited.

Answer 3

I would give them some maintenance work on some code with variables called x, y, z and let them realise for themselves that readability is vital...

95% of code viewing is not by the author, but by the customer that everyone forgets about - the next programmer. You owe it to her to make her life easy.

Answer 4

Good variable names describe exactly what they are without being overly complex. I always use descriptive names, even in loops (for instance, index instead of i). It helps keep track of what's going on, especially when I'm working on rewriting a particularly complex piece of code.

Answer 5

Well give them a chunk of bad code and ask them to debug it.
Take the following code (simple example)

<?php $a = fopen('/path/to/file.ext', 'w');$b = "NEW LINE\n";fwrite($a, $b);fclose($a);?>

The bug is: File only ever contains 1 line when it should be a log Problem: 'w' in fopen should be 'a'

This obviously is a super easy example, if you want to give them a bigger more complicated example give them the WMD source and ask them to give you readable code in 2 hours, it will get your point across.

Answer 6

x,y and z are acceptable variable names if they represent 3d coordinates, or if they're used for iterating over 2 or 3 dimensional arrays.

This code is fine as far as I'm concerned:

for(int x = 0; x < xsize ; x++)
{
  for(int y = 0; y < ysize ; y++)
  {
    for(int z = 0; z < zsize ; z++)
    {
      DoSomething(data[x][y][z]);
...

Answer 7

As long as x, y and z are (3D) Cartesian co-ordinates, then they're great names.

In a similar vein, i, j and k would be OK for loop variables.

In all cases, the variable names should relate to the data

Answer 8

As already stated x, y, and z are good variables for 3D coordinates but probably bad for anything else...

If someone does not believe that names are important, just use a code obfuscator on some code then ask them to debug it :-).

(BTW that's the only situation where a code obfuscator can be useful IMHO)

Answer 9

This one is a short answer, but it works very well for me:

If it would need a code comment to describe it, then rethink the variable name.

So if it's obvious, why "x" was choosen, then they are good names. E.g. "i" as variable name in a loop is (often) pretty obvious.

Answer 10

An ideal variable name is both short (to make the code more compact) and descriptive (to help understanding the code).

Opinions differ on which of the two is more important. Personally, I'd say it depends on the scope of the variable. A variable used only inside a 3 line loop can get away with being single letter. A class field in a 500 line class better be pretty damn descriptive. The Spartan Programming philosophy says that as far as possible, all units of code should be small enough that variable names can be very short.

Answer 11

Readable code and good naming conventions are not the same thing!

A good name for a variable is one that allows you to understand (or reasonably guess) the purpose and type of the variable WITHOUT seeing the context in which it is used. Thus, "x" "y" and "z" say coordinates because that is a reasonable guess. Conversely, a bad name is one that leads you to a wrong likely guess. For example, if "x" "y" and "z" represent people.

A good name for a function is one that conveys everything you would need to know about it without having to consult its documentation. That is not always possible.

Readable code is first of all code whose structured could be understood even if you obfuscated all variable and function names. If you do that and can't figure out the control structure easily, you're screwed.

Once you have readable code and good naming, then maybe you'll have truly readable code.

Answer 12

There seems to be slightly different conventions per progamming language; however, the consensus these days is to...

• use pascal case
• make the name meaningful
• end with a noun

Here is a decent recap of what Microsoft publishes as standard naming conventions for .NET

The inventor of python has published a style guide which includes naming conventions.

There was a time when Microsoft VC++ developers (myself included) actually rallied around what was known as Hungarian Notation

Answer 13

Readable code means some combination of comments and variable and function naming that allows me to read the code once and understand it. If I have to read it more than once, or spend my time working through complicated loops or functions, there's room for improvement.

Good summary descriptions at the top of files and classes are useful to give the reader context and background information.

Clear names are important. Verbose names make it much easier to write readable code with far fewer comments.

Writing readable code is a skill that takes some time to learn. I personally like overly verbose names because they create self documenting code.