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.

  • 1
    $\begingroup$ 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. $\endgroup$ – Rory Jun 9 '17 at 12:33
  • 1
    $\begingroup$ @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. $\endgroup$ – ItamarG3 Jun 9 '17 at 12:52
  • 2
    $\begingroup$ @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. $\endgroup$ – Rory Jun 9 '17 at 12:52
  • 2
    $\begingroup$ 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?) $\endgroup$ – Ben I. Jun 9 '17 at 12:53
  • 1
    $\begingroup$ This answer about indentation is good - cseducators.stackexchange.com/a/132/57 $\endgroup$ – Rory Jun 9 '17 at 12:57

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:

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.

  • $\begingroup$ I could not have asked for a more thorough answer. Thanks! $\endgroup$ – ItamarG3 Jun 9 '17 at 13:49
  • $\begingroup$ and assure them that good names, consistency and indentation will allow them to learn quicker. $\endgroup$ – ctrl-alt-delor Jun 9 '17 at 16:49

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.

  • $\begingroup$ 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. $\endgroup$ – Ben I. Jun 10 '17 at 13:52

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.

  • 1
    $\begingroup$ 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. $\endgroup$ – G. Ann - SonarSource Team Jun 9 '17 at 12:51

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


Not the answer you're looking for? Browse other questions tagged or ask your own question.