<p>I teach the "standard" conventions for the language, where they exist. For Java, I use the <a href="http://www.oracle.com/technetwork/java/javase/documentation/codeconventions-135099.html" rel="nofollow noreferrer">original Sun naming conventions</a> and <a href="https://google.github.io/styleguide/javaguide.html#s5-naming" rel="nofollow noreferrer">Google Java Style Guide</a>. </p>

<p>More important that standard capitalization (which I require) are:</p>

<ul>
<li>Using a noun for class names.</li>
<li>Using a verb for method names (with certain stereotypical exceptions, such as <code>toString</code>).</li>
</ul>

<p>Choosing good names for classes and methods helps students think clearly. As the great Josh Bloch <a href="https://www.infoq.com/articles/API-Design-Joshua-Bloch" rel="nofollow noreferrer">says</a>:</p>

<blockquote>
  <p>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.</p>
  
  <p>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.</p>
</blockquote>

<p>The care put into a variable name should be proportional to its lifetime. I consider a single letter <code>i</code> appropriate for an integer loop variable<sup>1</sup> or a short-lived temporary variable, while classes and members<sup>2</sup> should be named carefully.</p>

<p><strong>Footnotes</strong></p>

<ol>
<li>In Programming Languages, I tell students that, in Fortran 77, the default type of a variable starting with <code>I</code>, <code>J</code>, <code>K</code>, <code>L</code>, <code>M</code>, or <code>N</code> 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)."</li>
<li>I recently learned about the deprecated <a href="https://blog.codinghorror.com/new-programming-jargon/" rel="nofollow noreferrer">Smurf Naming Convention</a>.</li>
</ol>

CC BY-SA 3.0
2017-07-11T02:52:12.180Z
2017-07-11T02:52:12.180Z
Ellen Spertus
<p>I think that naming conventions are very important. It can be useful to explain that it makes the code much easier to understand.</p>

<p>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 <code>num</code> or <code>a</code> instead of <code>sum</code> or preferably <code>arraySum</code>). </p>

<p>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. </p>

<p>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).</p>

CC BY-SA 3.0
2017-06-09T10:58:09.417Z
2017-06-09T10:58:09.417Z
ItamarG3
<p>Some of the best information I have heard about how to name variables, methods, etc. comes from the Stanford MOOC on iTunes: <a href="https://itunes.apple.com/us/course/developing-ios-10-apps-with-swift/id1198467120" rel="nofollow noreferrer">Developing iOS 10 Apps with Swift</a>.</p>

<p>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. </p>

<p>One of the early requirements for the first assignment is to read through the <a href="https://swift.org/documentation/api-design-guidelines/" rel="nofollow noreferrer">Swift API Guidelines</a>. 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.</p>

<p>Even just the following two would be a great start for most students:</p>

<ul>
<li><p><strong>"Clarity is more important than brevity."</strong></p></li>
<li><p><strong>"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."</strong></p></li>
</ul>

CC BY-SA 3.0
2017-06-09T21:34:49.580Z
2017-06-09T21:34:49.580Z
Peter
<p>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.</p>

<p>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.</p>

<p>The critical aim is for intelligibility. Showing some examples is very useful, and even if Hungarian notation is not <em>in vogue</em> 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...</p>

CC BY-SA 3.0
2017-06-09T16:57:37.383Z
Nobody should antagonize the kernel devs! Purpose should be the consideration not "style" although that has its place too.
Gypsy Spellweaver
CC BY-SA 3.0
2017-06-09T14:15:57.097Z
2017-06-09T14:15:57.097Z
Sean Houlihane
<p>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.</p>

<p>Is there a notation suggested for learners?</p>

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

CC BY-SA 3.0
2017-06-09T16:52:13.790Z
What language? Hungarian notation is good for assembler language (and pointers in C).
ctrl-alt-delor
CC BY-SA 3.0
2017-06-09T16:55:55.253Z
Are you asking “What conventions should I use?”, or how do I encourage good practice? — https://cseducators.stackexchange.com/questions/505/the-importance-of-writing-understandable-code
ctrl-alt-delor
CC BY-SA 3.0
2017-06-09T20:13:31.863Z
@richard The first mostly. Also, that question you quoted was asked an hour after mine, so I can't have duplicated it.
vacip
CC BY-SA 3.0
2017-06-10T07:44:10.840Z
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?
ctrl-alt-delor
CC BY-SA 3.0
2017-06-11T14:42:57.450Z
@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.
vacip
<coding-style>
Teaching identifier naming conventions
# Teaching identifier naming conventions

(Asked by: username_0 on 2017-06-09)

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?

**Tags:** coding-style

> **Comments:**
> **username_1**: What language? Hungarian notation is good for assembler language (and pointers in C).  
> **username_1**: Are you asking “What conventions should I use?”, or how do I encourage good practice? — https://cseducators.stackexchange.com/questions/505/the-importance-of-writing-understandable-code  
> **username_0**: @richard The first mostly. Also, that question you quoted was asked an hour after mine, so I can't have duplicated it.  
> **username_1**: 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?  
> **username_0**: @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.  

---

## 4 answers

### Answer by username_3 on 2017-06-09. Score: 2 | Accepted answer

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).


---

### Answer by username_4 on 2017-06-09. Score: 4

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](https://itunes.apple.com/us/course/developing-ios-10-apps-with-swift/id1198467120).

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](https://swift.org/documentation/api-design-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."**


---

### Answer by username_5 on 2017-06-09. Score: 3

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...

> **Comments:**
> **username_6**: Nobody should antagonize the kernel devs! Purpose should be the consideration not "style" although that has its place too.  

---

### Answer by username_2 on 2017-07-11. Score: 2

I teach the "standard" conventions for the language, where they exist. For Java, I use the [original Sun naming conventions](http://www.oracle.com/technetwork/java/javase/documentation/codeconventions-135099.html) and [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html#s5-naming).

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](https://www.infoq.com/articles/API-Design-Joshua-Bloch):

> 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](https://blog.codinghorror.com/new-programming-jargon/).


---

