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
This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License