Document Code with Meaningful Comments (Activity)

From Foss2Serve
Revision as of 19:17, 26 May 2015 by Rmezei (Talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search
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

CC license.png

Personal tools
Learning Resources
HFOSS Projects