<p>Have the students read (actual) code of varying qualities written by others. Then they should be tasked with reviewing/critiquing/modifying it. </p>

<p>Once they are placed in the readers' shoes, they will better understand the importance of making code readable.</p>

<p>Surprisingly, the better students at this are often the English, language, and some liberal arts types, because they are used to working with parsing, declensions, and grammar. It might be the math types that give this aspect of the job short shrift because they are used to thinking "conceptually."</p>

CC BY-SA 3.0
2017-06-11T13:27:55.613Z
2017-06-11T13:27:55.613Z
Tom Au
<p>There are a ton of blog posts and several books on the topic of readable code, containing far more eloquent and complete arguments than one can make here (or that I could come up with myself). Depending on their level it's well worth sharing some extracts of well-written texts directly to show the importance of understandable code. </p>

<p>The most fundamental reasoning behind readable code is that <strong>people need to read code</strong>, not just computers. Or like @ben-i says <a href="https://cseducators.stackexchange.com/a/132/57">here</a>: </p>

<blockquote>
  <p>First, <em>right from the beginning</em>, and repeatedly, I talk about the
  two audiences for code: the computer <strong>and people</strong>. These two
  audiences have completely different needs. I come back to this theme
  with every new structure that I talk about, discussing coding style
  and norms with if statements, variable declarations (naming
  conventions), for loops (hey, why do we avoid break statements?), etc.</p>
</blockquote>

<p>Novice programmers typically give their total focus to getting code to do what they want: make it compile and then give the right output. That's really hard when you're starting out, and it's understandable that they give 'working' priority over any other qualities like 'readability'. As they mature, programmers learn that making some code work isn't the only goal. Once you can write code that works you realise there are other things to achieve too, which is where all other sorts of software engineering practices come in.</p>

<p>Readability is super important because <strong>most code will be read many many times more than it will be written</strong>. I think this is the most important message to get across, and it drives all the different aspects like formatting &amp; naming. I suggest teaching and discussing this core concept and keep coming back to it whenever talking about a new aspect. </p>

<p>It's one thing to get students to understand the importance, but another thing to make them bother to do it when 'getting it working' is so much more an immediate problem. To some extent that's fine, but even novice programmers should be taught the value of writing readable code because it makes their own coding easier. </p>

<p>I guess there's a few approaches that can be used in tandem: </p>

<ul>
<li><p>Discuss why it's important. Perhaps a sports analogy: when you're starting out with <em>[insert sport here]</em> you just care about hitting the ball <em>(etc)</em>. But the top sportspeople in the world spend all their time honing their technique to get better results. Writing readable code is one of the things that professional programmers spend time improving and perfecting all their careers. It makes you better. It makes you faster. It lets you achieve far greater things. It helps you work as a team. </p></li>
<li><p>Break down different aspects of readability and give exercises on them, the simplest being to have students write and also review code where the approach hasn't been followed at all, e.g. with indenting, bad variable naming, bad comments, etc. Get them to desk-check the execution or result of some poorly written code versus well-written code.</p></li>
<li><p>Have them read &amp; discuss articles about readability &amp; maintainability. Depending on what level the students are at they should given reading about this and discuss it in class, even just to appreciate that it's an important ongoing topic in the CS community.</p></li>
<li><p>Mark them down for various aspects of poor readability. Even if they just follow the rules for the benefit of marks that's better than not doing it; gets them into the practice and at some point they'll appreciate it. </p></li>
<li><p>Have them review other students code regularly, either in a group or individual setting. </p></li>
<li><p>Teach the benefit of readable code <em>as you're writing it</em>. Once you're writing more than a trivial piece of code you always have to re-read it and think about what's going on. It's difficult even for the original author to read poorly-written code; by following guidelines to write readable code they will actually find it easier to write code. </p></li>
</ul>

CC BY-SA 3.0
2017-06-09T13:49:32.197Z
I could not have asked for a more thorough answer. Thanks!
ItamarG3
CC BY-SA 3.0
2017-06-09T16:49:02.740Z
and assure them that good names, consistency and indentation will allow them to learn quicker.
ctrl-alt-delor
CC BY-SA 3.0
2017-06-09T13:45:14.683Z
2017-06-09T13:45:14.683Z
Rory
<p>The best motivator for my classes on this has been to conduct a code review of a recent assignment.</p>

<p>I take one or two student-submitted solutions to an assignment, and as a class we go through and read them, and try to understand what the author intended. Along the way, we discuss things the author did well, along with things they the author could improve. Readability is usually the number 1 issue with the reviewed programs, especially early in a course.</p>

<p>Using an actual program from a student in the class can be problematic because that student can feel called-out, while other students may be reluctant to criticize a classmate's code. Thus, I pull a solution from a previous class, and everybody knows that it is such.</p>

<p>I also think introducing the idea of readability at the right time is important. Students won't internalize the idea early on in a first programming course, when they're grappling with new, abstract concepts, and can barely get their programs to work. I start regularly discussing readability around the time we introduce functions.</p>

CC BY-SA 3.0
2017-06-10T13:52:57.047Z
I've been considering using public code reviews, but have wondered about that exact problem. That is quite an elegant solution! (I will have to go back several years, given my [recent grading practices](https://cseducators.stackexchange.com/questions/130/how-to-teach-why-indentation-is-important).
Ben I.
CC BY-SA 3.0
2017-06-10T13:31:25.543Z
2017-06-10T13:31:25.543Z
Chris Bay
<p>Give them some good and bad code. Ask them to modify it to do something else in addition. Let them see for themselves that it's much easier to understand well-written code than poorly written.</p>

CC BY-SA 3.0
2017-06-09T12:51:05.920Z
I like the approach but doubt it will work. Coding conventions allow the part of your brain that parses _what_ you're looking at to run on autopilot so you can concentrate on the _what's it doing_. But learners aren't at a level to have an autopilot yet. They're always fully concentrated on all aspects. So they won't notice the lack.
G. Ann - SonarSource Team
CC BY-SA 3.0
2017-06-09T11:17:23.373Z
2017-06-09T11:17:23.373Z
Scimonster
<p>Many students do not see the purpose of following conventions (indentation, naming, comments, etc.) which make the code much easier to read and review. </p>

<p>Students can learn to follow conventions, but often it is because they were simply told "That's how you do it", or by points being taken off assignments due to these things. Such conventions exist to make it easier for others to read and makes it possible for them to understand what it does, without too much effort. </p>

<p>If the students understood why the conventions exist and the reasons for writing easy-to-read code, they would write code which is easier to review. So my question is how can I teach the students the need for those conventions, so that they understand why it's important to write code that is easy to review.</p>

<p>I'd rather they didn't lose points in tests for not following conventions, because then they do learn the conventions but they don't understand the reason for those conventions.</p>

CC BY-SA 3.0
2017-06-09T11:19:26.337Z
@thesecretmaster this isn't about the value, showing that there's an acceptable norm, and that they should follow it
ItamarG3
CC BY-SA 3.0
2017-06-09T11:21:45.323Z
Why it's important == value, understandable == best practices.
thesecretmaster
CC BY-SA 3.0
2017-06-09T11:26:56.150Z
@thesecretmaster still a duplicate?
ItamarG3
CC BY-SA 3.0
2017-06-09T11:34:40.827Z
I think so. You reworded it but didnt change the meaning of the question.
thesecretmaster
CC BY-SA 3.0
2017-06-09T11:43:25.267Z
@thesecretmaster ok, fair enough.
ItamarG3
CC BY-SA 3.0
2017-06-09T12:33:08.883Z
I think the 'best practices' question is very broad and there's value in having this as a separate one. There are different approaches to teaching people to use source control versus writing readable code, so it's ok to have different questions.
Rory
CC BY-SA 3.0
2017-06-09T12:49:48.597Z
@Rory The other question is about best practices generally, including VCS, commenting, indentation, etc.
thesecretmaster
CC BY-SA 3.0
2017-06-09T12:52:24.840Z
@thesecretmaster but it asks about teaching them and ensuring students continue with those best practices. Here I'm asking about ways for students to *understand* why coding conventions are necessary for writing understandable code, as well as the importance of those conventions.
ItamarG3
CC BY-SA 3.0
2017-06-09T12:52:41.210Z
@thesecretmaster - exactly. I meant my statement as a vote towards not closing this one, since the other question is broader. Therefore this should remain as an open question.
Rory
CC BY-SA 3.0
2017-06-09T12:53:48.297Z
If anything, this question seems *more specific* to me, as the other question is also about testing and "VCS".  The previous question is possibly too broad (are we really going to avoid any further discussions about the reasoning behind readable code?)
Ben I.
CC BY-SA 3.0
2017-06-09T12:57:17.350Z
This answer about indentation is good - https://cseducators.stackexchange.com/a/132/57
Rory
CC BY-SA 3.0
2017-06-09T13:01:58.317Z
@Rory Thanks. I looked at that, and it has helped me with a part of my question. It does give me a general Idea how it could be done, but teaching indentation only goes so far.
ItamarG3
CC BY-SA 3.0
2017-06-09T14:01:51.933Z
I don't see this question covering substantially different ground to the other two linked examples. You changed the spelling of the title, but it has the same meaning. Is the answer different to 'code is for people to read'? An answer of 'bugs are easier to spot in templated code' does not match your question.
Sean Houlihane
CC BY-SA 3.0
2017-06-09T14:07:12.860Z
@SeanHoulihane You are quite right that the questions might be covering *similar* ground. However, my question is about students gaining a deeper understanding of the conventions, and why they are important. As I see it, the bullets in Rory's answer address *that* very well. Would I have asked how to show them just how bad it would be if they didn't follow conventions, then the questions would be much more alike.
ItamarG3
CC BY-SA 3.0
2017-06-11T20:35:54.640Z
Suggested new title 'The importance of wrtiting code where the intent is explicit'. I don't quite like that title, but feels closer to what you're asking, maybe.
Sean Houlihane
<coding-style>
The importance of writing understandable code
# The importance of writing understandable code

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

Many students do not see the purpose of following conventions (indentation, naming, comments, etc.) which make the code much easier to read and review.

Students can learn to follow conventions, but often it is because they were simply told "That's how you do it", or by points being taken off assignments due to these things. Such conventions exist to make it easier for others to read and makes it possible for them to understand what it does, without too much effort.

If the students understood why the conventions exist and the reasons for writing easy-to-read code, they would write code which is easier to review. So my question is how can I teach the students the need for those conventions, so that they understand why it's important to write code that is easy to review.

I'd rather they didn't lose points in tests for not following conventions, because then they do learn the conventions but they don't understand the reason for those conventions.

**Tags:** coding-style

> **Comments:**
> **username_0**: @username_1 this isn't about the value, showing that there's an acceptable norm, and that they should follow it  
> **username_1**: Why it's important == value, understandable == best practices.  
> **username_0**: @username_1 still a duplicate?  
> **username_1**: I think so. You reworded it but didnt change the meaning of the question.  
> **username_0**: @username_1 ok, fair enough.  
> **username_2**: I think the 'best practices' question is very broad and there's value in having this as a separate one. There are different approaches to teaching people to use source control versus writing readable code, so it's ok to have different questions.  
> **username_1**: @username_2 The other question is about best practices generally, including VCS, commenting, indentation, etc.  
> **username_0**: @username_1 but it asks about teaching them and ensuring students continue with those best practices. Here I'm asking about ways for students to *understand* why coding conventions are necessary for writing understandable code, as well as the importance of those conventions.  
> **username_2**: @username_1 - exactly. I meant my statement as a vote towards not closing this one, since the other question is broader. Therefore this should remain as an open question.  
> **username_3**: If anything, this question seems *more specific* to me, as the other question is also about testing and "VCS".  The previous question is possibly too broad (are we really going to avoid any further discussions about the reasoning behind readable code?)  
> **username_2**: This answer about indentation is good - https://cseducators.stackexchange.com/a/132/57  
> **username_0**: @username_2 Thanks. I looked at that, and it has helped me with a part of my question. It does give me a general Idea how it could be done, but teaching indentation only goes so far.  
> **username_4**: I don't see this question covering substantially different ground to the other two linked examples. You changed the spelling of the title, but it has the same meaning. Is the answer different to 'code is for people to read'? An answer of 'bugs are easier to spot in templated code' does not match your question.  
> **username_0**: @SeanHoulihane You are quite right that the questions might be covering *similar* ground. However, my question is about students gaining a deeper understanding of the conventions, and why they are important. As I see it, the bullets in username_2's answer address *that* very well. Would I have asked how to show them just how bad it would be if they didn't follow conventions, then the questions would be much more alike.  
> **username_4**: Suggested new title 'The importance of wrtiting code where the intent is explicit'. I don't quite like that title, but feels closer to what you're asking, maybe.  

---

## 4 answers

### Answer by username_2 on 2017-06-09. Score: 9 | Accepted answer

There are a ton of blog posts and several books on the topic of readable code, containing far more eloquent and complete arguments than one can make here (or that I could come up with myself). Depending on their level it's well worth sharing some extracts of well-written texts directly to show the importance of understandable code.

The most fundamental reasoning behind readable code is that **people need to read code**, not just computers. Or like @ben-i says [here](https://cseducators.stackexchange.com/a/132/57):

> First, *right from the beginning*, and repeatedly, I talk about the
> two audiences for code: the computer **and people**. These two
> audiences have completely different needs. I come back to this theme
> with every new structure that I talk about, discussing coding style
> and norms with if statements, variable declarations (naming
> conventions), for loops (hey, why do we avoid break statements?), etc.

Novice programmers typically give their total focus to getting code to do what they want: make it compile and then give the right output. That's really hard when you're starting out, and it's understandable that they give 'working' priority over any other qualities like 'readability'. As they mature, programmers learn that making some code work isn't the only goal. Once you can write code that works you realise there are other things to achieve too, which is where all other sorts of software engineering practices come in.

Readability is super important because **most code will be read many many times more than it will be written**. I think this is the most important message to get across, and it drives all the different aspects like formatting & naming. I suggest teaching and discussing this core concept and keep coming back to it whenever talking about a new aspect.

It's one thing to get students to understand the importance, but another thing to make them bother to do it when 'getting it working' is so much more an immediate problem. To some extent that's fine, but even novice programmers should be taught the value of writing readable code because it makes their own coding easier.

I guess there's a few approaches that can be used in tandem:

* Discuss why it's important. Perhaps a sports analogy: when you're starting out with *[insert sport here]* you just care about hitting the ball *(etc)*. But the top sportspeople in the world spend all their time honing their technique to get better results. Writing readable code is one of the things that professional programmers spend time improving and perfecting all their careers. It makes you better. It makes you faster. It lets you achieve far greater things. It helps you work as a team.
* Break down different aspects of readability and give exercises on them, the simplest being to have students write and also review code where the approach hasn't been followed at all, e.g. with indenting, bad variable naming, bad comments, etc. Get them to desk-check the execution or result of some poorly written code versus well-written code.
* Have them read & discuss articles about readability & maintainability. Depending on what level the students are at they should given reading about this and discuss it in class, even just to appreciate that it's an important ongoing topic in the CS community.
* Mark them down for various aspects of poor readability. Even if they just follow the rules for the benefit of marks that's better than not doing it; gets them into the practice and at some point they'll appreciate it.
* Have them review other students code regularly, either in a group or individual setting.
* Teach the benefit of readable code *as you're writing it*. Once you're writing more than a trivial piece of code you always have to re-read it and think about what's going on. It's difficult even for the original author to read poorly-written code; by following guidelines to write readable code they will actually find it easier to write code.

> **Comments:**
> **username_0**: I could not have asked for a more thorough answer. Thanks!  
> **username_6**: and assure them that good names, consistency and indentation will allow them to learn quicker.  

---

### Answer by username_7 on 2017-06-10. Score: 3

The best motivator for my classes on this has been to conduct a code review of a recent assignment.

I take one or two student-submitted solutions to an assignment, and as a class we go through and read them, and try to understand what the author intended. Along the way, we discuss things the author did well, along with things they the author could improve. Readability is usually the number 1 issue with the reviewed programs, especially early in a course.

Using an actual program from a student in the class can be problematic because that student can feel called-out, while other students may be reluctant to criticize a classmate's code. Thus, I pull a solution from a previous class, and everybody knows that it is such.

I also think introducing the idea of readability at the right time is important. Students won't internalize the idea early on in a first programming course, when they're grappling with new, abstract concepts, and can barely get their programs to work. I start regularly discussing readability around the time we introduce functions.

> **Comments:**
> **username_3**: I've been considering using public code reviews, but have wondered about that exact problem. That is quite an elegant solution! (I will have to go back several years, given my [recent grading practices](https://cseducators.stackexchange.com/questions/130/how-to-teach-why-indentation-is-important).  

---

### Answer by username_8 on 2017-06-09. Score: 2

Give them some good and bad code. Ask them to modify it to do something else in addition. Let them see for themselves that it's much easier to understand well-written code than poorly written.

> **Comments:**
> **username_9**: I like the approach but doubt it will work. Coding conventions allow the part of your brain that parses _what_ you're looking at to run on autopilot so you can concentrate on the _what's it doing_. But learners aren't at a level to have an autopilot yet. They're always fully concentrated on all aspects. So they won't notice the lack.  

---

### Answer by username_5 on 2017-06-11. Score: 0

Have the students read (actual) code of varying qualities written by others. Then they should be tasked with reviewing/critiquing/modifying it.

Once they are placed in the readers' shoes, they will better understand the importance of making code readable.

Surprisingly, the better students at this are often the English, language, and some liberal arts types, because they are used to working with parsing, declensions, and grammar. It might be the math types that give this aspect of the job short shrift because they are used to thinking "conceptually."


---

