Document Code with Meaningful Comments (Activity)

From Foss2Serve
(Difference between revisions)
Jump to: navigation, search
(Created page with "{| border="1" |- |'''Title''' || A POGIL activity on documenting the code with meaningful comments! |- |'''Overview''' || In this POGIL activity students will define what ...")
 
 
(20 intermediate revisions by 6 users not shown)
Line 1: Line 1:
−
{| border="1"
+
__NOTOC__
−
|-
+
−
|'''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
+
{{Learning Activity Overview
 +
|title=
 +
Document Code with Meaningful Comments
 +
|overview=
 +
In this 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. 
 +
|prerequisites=
 +
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.
 +
|objectives=
 +
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.
 +
|process skills=
 +
}}
  
−
- 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!
+
=== Background ===
 +
CS 1 background should suffice.
  
−
- Teams will then be asked to write comments for the given code.
+
Some possible reading the instructors only (students should discover the idea of "meaningful comments"!):
  
−
- 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.
+
* http://blog.codinghorror.com/coding-without-comments/
 +
* http://improvingsoftware.com/2011/06/27/5-best-practices-for-commenting-your-code/
 +
* http://www.hongkiat.com/blog/source-code-comment-styling-tips/
 +
* http://en.wikipedia.org/wiki/Comment_%28computer_programming%29
 +
* http://javarevisited.blogspot.com/2011/08/code-comments-java-best-practices.html
 +
* http://code.tutsplus.com/tutorials/top-15-best-practices-for-writing-super-readable-code--net-8118
  
−
- 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.
+
=== Directions ===
  
−
-- All the students will have access to the entire project in case they want to look at the big picture while commenting the code.
+
# The entire class will be given a brief overview of a project. This can be chosen from the existing HFOSS projects that contain source files in the programming language used in the course.
 +
# Then the class will be split in teams of 2-3 students, and each team will be given one file of undocumented code that has an easy complexity level. 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". While presenting, based on students' reflections, the instructor will create a rubric to assess when a code has meaningful comments and when it does not.
 +
# Then, each team will be assigned a second file with undocumented code and they will be asked to write "meaningful comments". The students will meet again in one week and will have to present their work.
  
−
-- 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).
+
* All the students will have access to the entire project in case they want to look at the big picture while commenting the code. Depending on the complexity level, this may be a must have.
 +
* During the presentation, the other teams will assess each team's work using the rubric created in the first phase.
 +
* 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).
  
 +
=== Deliverables ===
  
−
|-
+
* A rubric that can be used to assess "meaningful comments"
−
|'''Author''' ||  Razvan A. Mezei
+
* Code with "meaningful comments" will be presented to the entire class.
−
|-
+
−
|'''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
+
=== Assessment ===
  
−
- a file with an easy code to document
+
=== Comments ===
  
−
- a file with a medium/hard code to document
+
=== Additional Information: ===
 +
{{Learning Activity Info
 +
|acm unit=
 +
Coding & Style
 +
|acm topic=
 +
Meaningful Comments
 +
|difficulty=
 +
Medium/Hard
 +
|time=
 +
A 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.
 +
|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
 +
|author=
 +
Razvan A. Mezei
 +
|source=
 +
50 Ways
 +
|license=
 +
{{License CC BY SA}}
 +
}}
  
−
|-
+
=== Suggestions for the Open Source Project: ===
−
|'''License''' ||
+
−
|}
+
  
−
 
+
[[Category:Learning_Activity]]
−
=== Background: ===
+
[[Category:Coding and Style]]
−
 
+
[[Category:Documentation]]
−
=== Directions: ===
+
[[Category:CS1]]
−
 
+
[[Category:CS2]]
−
=== Deliverables: ===
+
[[Category:Minimal Sketch]]
−
 
+
−
=== Assessment: ===
+
−
 
+
−
--------------------
+
−
This work is licensed under a
+
−
[http://creativecommons.org/licenses/by-sa/4.0/ Creative Commons Attribution-ShareAlike 4.0 International License]
+
−
 
+
−
[[File:CC_license.png]]
+
−
 
+
−
[[Category: Learning_Activity]]
+
−
[[Category: LEARNING_ACTIVITY_SUBCATEGORY]]
+

Latest revision as of 22:04, 7 September 2018


Title

Document Code with Meaningful Comments

Overview

In this 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.

Prerequisites

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.

Learning
Objectives 		After successfully completing this activity, the learner should be able to:

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.

Process Skills
Practiced


Background

CS 1 background should suffice.

Some possible reading the instructors only (students should discover the idea of "meaningful comments"!):

Directions

  1. The entire class will be given a brief overview of a project. This can be chosen from the existing HFOSS projects that contain source files in the programming language used in the course.
  2. Then the class will be split in teams of 2-3 students, and each team will be given one file of undocumented code that has an easy complexity level. Several teams will have the same assigned code!
  3. Teams will then be asked to write comments for the given code.
  4. Then, in class, students will present their work and define "meaningful comments". While presenting, based on students' reflections, the instructor will create a rubric to assess when a code has meaningful comments and when it does not.
  5. Then, each team will be assigned a second file with undocumented code and they will be asked to write "meaningful comments". The students will meet again in one week and will have to present their work.
  • All the students will have access to the entire project in case they want to look at the big picture while commenting the code. Depending on the complexity level, this may be a must have.
  • During the presentation, the other teams will assess each team's work using the rubric created in the first phase.
  • 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).

Deliverables

  • A rubric that can be used to assess "meaningful comments"
  • Code with "meaningful comments" will be presented to the entire class.

Assessment

Comments

Additional Information:

ACM BoK
Area & Unit(s)

Coding & Style

ACM BoK
Topic(s)

Meaningful Comments

Difficulty

Medium/Hard

Estimated Time
to Complete

A 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.

Environment /
Materials

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
Author(s)

Razvan A. Mezei

Source

50 Ways

License

This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License

CC license.png


Suggestions for the Open Source Project:

Retrieved from "http://foss2serve.org/index.php?title=Document_Code_with_Meaningful_Comments_(Activity)&oldid=12621"
Personal tools
Namespaces
Variants
Actions
Events
Learning Resources
HFOSS Projects
Evaluation
Navigation
Toolbox