Conventions in Code Writing
Objective: Students will be able to recognize and utilize a variety of conventions used in code writing.
Key Terms: Convention, audience, discipline field, code, stylistic choice.
Timing: These lessons could be particularly appropriate in any course where students are learning to write code, or in any course where students are learning to write code so that it can be more easily digested by other humans.
Conceptual Framework
Students may assume that, as long as the code runs and produces the desired output, then it does not need further work. However, there can be many pieces of code that all produce the same output, but they may arrive at that output by different means, or that code may be more or less easily digestible by another human. This can lead to less computationally efficient code, or more difficulty in collaborating with others in writing code.
When discussing conventions, it can be helpful to frame them not as rules that must be strictly adhered to, but rather as guidelines that can help make their code writing more clear for their intended audience. Moreover, it can be helpful to also discuss the concept of stylistic choice, and that there can be two successful codes that produce the same code that read very differently. However, often such stylistically different codes still adhere to a similar set of basic conventions. Furthermore, there can be times when it is desirable to explicitly violate a known convention, but if one is going to do so, it can be helpful to potentially flag that choice for the reader, and to explain why that choice is made.
Part I: Basic Code Writing Conventions
- Consider this Style Guide that is specific to the language Julia, this Python Pep 8 style guide, or any other style guide that is relevant for the language you want your students to work in.
- Assign the guide to students, as well as a piece of code of your choice that is tailored to your course. Students could do this work inside or outside of class. This could be, for example, a sample of anonymized student work, or a purpose-written sample that you create.
- Put the students into small groups.
- Have the students evaluate the sample code based on the conventions in the guide, and answer the following questions in their groups.
Questions about coding conventions
- Did the writing follow all of the suggested conventions?
- If places where it did not, did this affect the computational efficiency or the clarify of the writing? If so, how?
- Do you have any ideas why the author did not follow the conventions in those places?
Variations and Follow-Ups
Create a purpose-written sample that intentionally does not follow of the conventions described in the guide. Ask students to rewrite it so that it follows the conventions to a greater extent that it originally did. Also ask the students to identify places where they feel the conventions are not needed, and explain why.
Further Reading
“
Towards readable code in neuroscience,” by Juan Luis Riquelme and Julijana Gjorgjieva, Nature Reivews Neuroscience, vol 22, 2021 and/or “Good enough practices in scientific computing,” by Wilson et al, PLOS Computational Biology, 13(6), 017. There are more field-specific, but they may also be more readable than the above-linked guides, since they are written in essay format. You could also discuss linting; see for example these python linting tools.