Answers.Body: <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>
  
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2017-07-11T02:52:12.180Z
Answers.LastActivityDate: 2017-07-11T02:52:12.180Z
Answers.UserDisplayName: Ellen Spertus
Answers.Body: <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>
  
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2017-06-09T10:58:09.417Z
Answers.LastActivityDate: 2017-06-09T10:58:09.417Z
Answers.UserDisplayName: ItamarG3
Answers.Body: <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>
  
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2017-06-09T21:34:49.580Z
Answers.LastActivityDate: 2017-06-09T21:34:49.580Z
Answers.UserDisplayName: Peter
Answers.Body: <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>
  
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2017-06-09T16:57:37.383Z
Answers.Text: Nobody should antagonize the kernel devs! Purpose should be the consideration not "style" although that has its place too.
Answers.UserDisplayName: Gypsy Spellweaver
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2017-06-09T14:15:57.097Z
Answers.LastActivityDate: 2017-06-09T14:15:57.097Z
Answers.UserDisplayName: Sean Houlihane
Body: <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>
  
Comments.ContentLicense: CC BY-SA 3.0
Comments.CreationDate: 2017-06-09T16:52:13.790Z
Comments.Text: What language? Hungarian notation is good for assembler language (and pointers in C).
Comments.UserDisplayName: ctrl-alt-delor
Comments.ContentLicense: CC BY-SA 3.0
Comments.CreationDate: 2017-06-09T16:55:55.253Z
Comments.Text: 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
Comments.UserDisplayName: ctrl-alt-delor
Comments.ContentLicense: CC BY-SA 3.0
Comments.CreationDate: 2017-06-09T20:13:31.863Z
Comments.Text: @richard The first mostly. Also, that question you quoted was asked an hour after mine, so I can't have duplicated it.
Comments.UserDisplayName: vacip
Comments.ContentLicense: CC BY-SA 3.0
Comments.CreationDate: 2017-06-10T07:44:10.840Z
Comments.Text: 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?
Comments.UserDisplayName: ctrl-alt-delor
Comments.ContentLicense: CC BY-SA 3.0
Comments.CreationDate: 2017-06-11T14:42:57.450Z
Comments.Text: @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.
Comments.UserDisplayName: vacip
Tags: <coding-style>
Title: Teaching identifier naming conventions
ThreadText: # 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/).
  
  
  ---
  
  