Teaching identifier naming conventions

Currently the only thing I'm teaching for the naming of identifiers is "be consistent". Then I go ahead and use the Hungarian notation consistently, and show them a few other conventions.

Is there a notation suggested for learners?

Should the use of a consistent naming convention be part of the grading, or am I putting too much emphasis on this?

• What language? Hungarian notation is good for assembler language (and pointers in C). Jun 9 '17 at 16:52
• Are you asking “What conventions should I use?”, or how do I encourage good practice? — cseducators.stackexchange.com/questions/505/… Jun 9 '17 at 16:55
• @richard The first mostly. Also, that question you quoted was asked an hour after mine, so I can't have duplicated it. Jun 9 '17 at 20:13
• sorry if you thought I was accusing you of duplication. I was not, I was asking you a question, to clarify what you were asking. Which of the two meanings should we use to interpret your question? Jun 10 '17 at 7:44
• @richard Oh ok, sorry for misunderstanding then. I'm mostly looking for suggestions on what conventions should I use, and also on how strict should I enforce using them. Jun 11 '17 at 14:42

I think that naming conventions are very important. It can be useful to explain that it makes the code much easier to understand.

In the beginning (1 or 2 tests after introducing the convention), you should take just a few points off if the name of a variable or method doesn't tell you anything about it (e.g. calling the sum of an array num or a instead of sum or preferably arraySum).

You should tell them that you will take a few points for it. After a short amount of time, you'll find that you don't need to take points off for bad naming, because students will learn that it is important.

Again, just one or two points for bad naming should do the trick. However it is necessary to explain why it's important for their code to be easily understandable).

Some of the best information I have heard about how to name variables, methods, etc. comes from the Stanford MOOC on iTunes: Developing iOS 10 Apps with Swift.

In the first couple lectures, the professor talks through how to build a calculator app (and does so in front of the class in real time) and does a fantastic job of demonstrating why he is naming things the way he is. The essence, as he explains it, is this: a statement in code should read like an English sentence.

One of the early requirements for the first assignment is to read through the Swift API Guidelines. Admittedly, this is designed for the Swift language, but there are lessons to take away from this for any language. The naming can be verbose at times, but such verbosity might improve code comprehension as students will have to know what a variable or method does in order to name it properly.

Even just the following two would be a great start for most students:

• "Clarity is more important than brevity."

• "Write a documentation comment for every declaration. Insights gained by writing documentation can have a profound impact on your design, so don’t put it off."

There is a difference between having a clear convention for making identifier names (CamelCase, under_sep, abrev) and mandating that redundant information is provided in the code.

There is also the challenge that what is good for beginners isn't necessarily what makes sense for an experienced developer, and maybe your preference changes depending on the language you're coding in.

The critical aim is for intelligibility. Showing some examples is very useful, and even if Hungarian notation is not in vogue in general, it forms a good reference to practice with. By all means deduct marks for inconsistent, wrong (by context) or random naming, but be careful about enforcing a single style without good reason. You wouldn't want to turn out students programmed to antagonise the Linux kernel maintainer...

• Nobody should antagonize the kernel devs! Purpose should be the consideration not "style" although that has its place too. Jun 9 '17 at 16:57

I teach the "standard" conventions for the language, where they exist. For Java, I use the original Sun naming conventions and Google Java Style Guide.

More important that standard capitalization (which I require) are:

• Using a noun for class names.
• Using a verb for method names (with certain stereotypical exceptions, such as toString).

Choosing good names for classes and methods helps students think clearly. As the great Josh Bloch says:

Names matter. Strive for intelligibility, consistency, and symmetry. Every API is a little language, and people must learn to read and write it. If you get an API right, code will read like prose.

If it's hard to find good names, go back to the drawing board. Don't be afraid to split or merge an API, or embed it in a more general setting. If names start falling into place, you're on the right track.

The care put into a variable name should be proportional to its lifetime. I consider a single letter i appropriate for an integer loop variable1 or a short-lived temporary variable, while classes and members2 should be named carefully.

Footnotes

1. In Programming Languages, I tell students that, in Fortran 77, the default type of a variable starting with I, J, K, L, M, or N is integer, while variables starting with any other character are reals. In either case, the default can be overridden with an explicit declaration. That sets up the joke: "Fortran is of great theological importance, because GOD is real (unless declared integer)."
2. I recently learned about the deprecated Smurf Naming Convention.