Document Code with Meaningful Comments (Activity)
| Title | A POGIL activity on documenting the code with meaningful comments! |
| Description | In this POGIL activity students will define what "meaningful comments" mean and create a rubric for it. Then, they will create meaningful comments for a given source file with undocumented code. |
| Source | 50 ways |
| Level of Difficulty | Medium/Hard |
| Prerequisite Knowledge | The instructor can tailor this activity to match the current content being taught in a CS 2 course. Therefore it could be appropriate at any time during the CS 2 course. |
| Estimated Time to Completion | Total of 120 minutes is suggested. The first part can be done in class, while the second part can be given as a week-long project and then in another class period each team will have to present their code. All students will rate (based solely on the comments) the readability of the code being presented by each team. |
| Learning Objectives | This is a POGIL activity and students should define “meaningful comments”. They will create a rubric for this. Each team will make use of this rubric when commenting/documenting the second source file. |
| Materials/Environment | Each team will be given three materials:
- a source file of a (more or less) complete project without any comments - a file with an easy code to understand and document - a file with a medium/hard code to understand and document |
| Rights | Licensed CC BY-SA |
| Turn In | Code with "meaningful comments" will be presented to the entire class. |
Background:
CS 1 background should suffice.
Directions:
For this:
- The entire class will be given a brief overview of a project
- Then the class will be split in teams of 2-3 students, and each team they will be given one file of undocumented code that has an easy complexity. Several teams will have the same assigned code!
- Teams will then be asked to write comments for the given code.
- Then, in class, students will present their work and define "meaningful comments". Maybe even create a rubric to assess when a code has meaningful comments or not.
- Then, teams will be assigned a second file with undocumented code and will be asked to write "meaningful comments". The students will meet again in one week and will have to present their code.
--> All the students will have access to the entire project in case they want to look at the big picture while commenting the code.
--> If time is available, it may be useful to compare the "meaningful comments" of students with the original comments existing in the code (but which was not made available to students).
This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License
