Document Code with Meaningful Comments (Activity)
| Title | A POGIL activity on documenting the code with meaningful comments! |
| Overview | In this POGIL activity students will define what "meaningful comments" mean. 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).
|
| Author | Razvan A. Mezei |
| Source | Any HFOSS project that contains code written in a programming language that is being used in your CS2 course. |
| Knowledge Area/Knowledge Unit | |
| Topic | Coding and style |
| Level of Difficulty | Medium/Hard |
| Prerequisite Knowledge | The instructor can tailor this depending on when he/she wants to work on this activity. Being in a CS2 course, any time could be appropriate. |
| Estimated Time to Completion | The first part can be done in class, while the second file can be given as a week-long project and then in a class period each will have to present their code. Their colleagues will rate the readability of the code based solely on the comments. |
| Learning Objectives | This is a POGIL activity and students should define “meaningful comments”. They will make use of this by commenting/documenting a given 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 document - a file with a medium/hard code to document |
| License |
Contents |
Background:
Directions:
Deliverables:
Assessment:
This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License
