The International Society for Technology in Education (ISTE) is passionate about the power of technology to transform teaching and learning. The ISTE Standards provide a framework that allows students and computer science educators (as well as other educators) to create innovative learning environments. In particular, the ISTE Standard for Students are designed to empower students and to ensure that learning is a student-driven process. I want to focus on the empowered learner, and how computer science students can use technology to inform and improve their computer programming skills and demonstrate their learning in a variety of ways.
Like many subject areas, software engineering is witnessing rapid change. As stated in [Bates, n.d.], “… it is difficult to predict with any accuracy what many graduates will actually be doing ten or so years after graduation, except in very broad terms.” However, one aspect of computer programming that has remained the same, even as new development environments, programming languages and other tools have changed and evolved, is the need to comment code. Students must realize that comments in the code they write serve multiple audiences. The first audience is their future self, when they come back to their own code to make improvements or fix bugs. The second audience is the future developer that will take over responsibility for fixing bugs and adding new features to the code. Finally, the third audience is the developer that will invoke the code from other code.
The challenge with getting computer science students to write good comments is having students empathize with these three audiences. Typically, computer science students spend very little time commenting their code, leaving it to the last thing done before submitting their assignment. The students are only thinking about the bar set by the instructor for acceptable amount of comments that will not impact their assignment grade. Many of my fellow computer science instructors have no commenting component in their grading rubric for coding assignments.
Even when students put comments in their code, the comments often fall into the bad and ugly traps described in the article ‘Putting comments in code: the good, the bad, and the ugly’ by [Sourour, 2017]. One creative solution to this problem leverages the set of tools described at the beginning of the [Sourour, 2017] article. Specifically, students can benefit from the code documentation tools such as JSDoc and JavaDoc for adding comments to JavaScript and Java code, respectively. Even though these tools were built for documenting Application Programming Interfaces (APIs), both tools require the programmer to follow strict commenting conventions and make comments presentable to an outside reader.
The full solution to the code commenting problem requires one more step. As mentioned, students typically only write comments with the target audience of the instructor and the goal of passing grading requirements. However, by asking another student to read the comments generated by their classmate, students now have to consider another audience. Furthermore, you can ask the other student to put themselves in the shoes of the developer that has to maintain their classmate’s code as well as the shoes of a developer that has to call or re-use their classmate’s code. The students reading their classmate’s comments would use the output from the JSDoc or JavaDoc tools, and give feedback to the student who authored the comments, as well as present their understanding of the reviewed code to the entire class.
My role as a computer science educator is to constantly be on the lookout for new and better tools to improve computer science education. In the article ‘Emerging technologies for education’, [Mecklenburger, 1986] tells us the importance of this role:
The challenge to educators and to educational policy is to exploit what has become available. If we do not, others will. We cannot tread water any longer, or the social and financial base for public education institutions will continue to erode compared to other educational investment.
References
- Bates, A. W. (n.d.). Fundamental change in education. Teaching in a digital age. Retrieved from https://opentextbc.ca/teachinginadigitalage/part/chapter-1-fundamental-change-in-education/
- Guzel, Burak. (2011). Top 15+ Best Practices for Writing Super Readable Code. https://code.tutsplus.com/tutorials/top-15-best-practices-for-writing-super-readable-code–net-8118
- ISTE, International Society for Technology in Education, http://www.iste.org
- Mecklenburger, J. A. (1986). “Emerging” technologies for education. Peabody Journal of Education, 64(1), 183-187.
- Sourour, Bill. (2017). Putting comments in code: the good, the bad, and the ugly. https://medium.freecodecamp.org/code-comments-the-good-the-bad-and-the-ugly-be9cc65fbf83
Nat, the solution you present with using peer feedback is such a great way to help students understand the importance of code commenting outside of themselves. Also, pushing students past just ‘making the grade’ and instead seeing the importance of code commenting for what it is – help in the future for themselves and others – which is also a great example of taking the learning to the next step of WHY it is important for them to be doing it thoughtfully. Wonderful blog post and the ideas presented can be applied to so many aspects of digital education not just for writing code and code comments. Thanks for this!
Nat,
I think that if your students have your advice of the three audiences in the forefront of their mind when creating coding comments it will serve them well. I like how you broke it down into three audiences that will eventually look at the code. I agree that most students just think about who is looking at the assignment now. This type of reflection really brings in the actuality of the future. I think that you have come up with a great solution of having the students role-play as one of the audiences when giving them feedback. This will also help with them thinking through the lens of a developer, which will be helpful if that is indeed in their future.
Nat,
I can see from your solution the JSDoc or JavaDoc are good tools can make students code understandable to others which can lead to collaborative learning with peers and also can demonstrate students understanding of their code. These tools can help teachers to get valuable feedback from learners to clear misunderstanding immediately. When students are sharing their code with comments, they also present their digital citizenship from readable and credible comments which might help others to get a solution on their code. They are useful tools for a computer science class. Thanks for your sharing.
Nat,
You share systematic ways to support your students as they provide feedback with intent. This will help them become better coders that will be able to work past the basics of coding. You are intentionally empowering them prepare for projects in the workplace by having them look past the grade. You are teaching them to anticipate the needs from multiple perspectives. This is a valuable critical thinking skill that will serve them well in and outside of the classroom. Thank you for the thought that went into this post.