Review Coding Conventions

(Difference between revisions)
Jump to: navigation, search
(3 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
__NOTOC__
 
__NOTOC__
{| border="1"
+
 
 +
{| class="wikitable"
 
|-  
 
|-  
|'''Title''' || Coding Conventions Review
+
| '''Title''' || Review Coding Conventions
 
|-
 
|-
|'''Overview''' || Students review 1 or more samples of code to see how close sample(s) are to the HFOSS project coding conventions
+
| '''Overview''' || Students review 1 or more samples of code to see how close sample(s) are to the HFOSS project coding conventions
 
|-  
 
|-  
|'''Prerequisite Knowledge''' || Knowledge of the programming language for the HFOSS project to a level necessary to understand the coding conventions
+
| '''Prerequisite Knowledge''' || Knowledge of the programming language for the HFOSS project to a level necessary to understand the coding conventions
 
|-
 
|-
|'''Learning Objectives''' || Read and understand coding conventions for a large project; use standards to critique existing code; (optional) critique coding conventions
+
| '''Learning Objectives''' || Read and understand coding conventions for a large project; use standards to critique existing code; (optional) critique coding conventions
 
|}
 
|}
  
=== Background: ===
+
=== Background ===
  
 
[http://xkcd.com/1695/ XKCD: Code Quality 2]
 
[http://xkcd.com/1695/ XKCD: Code Quality 2]
Line 24: Line 25:
 
'''Are there other activities the student should have done first?''' No.
 
'''Are there other activities the student should have done first?''' No.
  
'''What is the rationale for this activity? Why are the learning objectives important?''' Students need practice reading other people's code. Students should appreciate the need for coding conventions, and seeing code where conventions are not applied is a good way to learn their value. If students are going to write code in an HFOSS project, they need to be able to apply the project's coding conventions themselves. Students may later contribute to the HFOSS project by revising the code so that it adheres to the coding conventions.
+
'''What is the rationale for this activity? Why are the learning objectives important?'''  
 +
Students need practice reading other people's code. Students should appreciate the need for coding conventions, and seeing code where conventions are not applied is a good way to learn their value. If students are going to write code in an HFOSS project, they need to be able to apply the project's coding conventions themselves. Students may later contribute to the HFOSS project by revising the code so that it adheres to the coding conventions.
  
 
'''Include helpful hints to faculty here.'''
 
'''Include helpful hints to faculty here.'''
Line 32: Line 34:
 
* For your class, is it important that this be a graded activity? Or could it be an ungraded, in-class activity?
 
* For your class, is it important that this be a graded activity? Or could it be an ungraded, in-class activity?
  
=== Directions: ===
+
=== Directions ===
 
'''What should the student do?'''
 
'''What should the student do?'''
  
Line 53: Line 55:
 
# Reflect: What style guidelines have you learned in other contexts that were not part of the project's conventions?  
 
# Reflect: What style guidelines have you learned in other contexts that were not part of the project's conventions?  
  
=== Deliverables: ===
+
=== Deliverables ===
 
'''What will the student hand in?'''
 
'''What will the student hand in?'''
 
Annotated code is one possibility.  Alternatively, using a template supplied, students will turn in written analysis of the code sample.  
 
Annotated code is one possibility.  Alternatively, using a template supplied, students will turn in written analysis of the code sample.  
  
=== Assessment: ===
+
=== Assessment ===
 
'''How will the activity be graded?'''
 
'''How will the activity be graded?'''
 
   
 
   
Line 64: Line 66:
 
Include sample assessment questions/rubrics.
 
Include sample assessment questions/rubrics.
  
{| border="1" class="wikitable"
+
{| class="wikitable"
 
! Criteria
 
! Criteria
 
! Level 1 (fail)
 
! Level 1 (fail)
Line 101: Line 103:
 
|}
 
|}
  
=== Comments: ===
+
=== Comments ===
 
What should the instructor know before using this activity?
 
What should the instructor know before using this activity?
  
Documentation for open source projects is often not well organized or maintained.   Consequently there may be several documents in the open source project that describe coding standards.   These documents need to be checked beforehand for consistency.   For instance in OpenMRS, see https://wiki.openmrs.org/display/docs/Code+Style and https://wiki.openmrs.org/display/docs/Coding+Conventions.
+
Documentation for open source projects is often not well organized or maintained.
 +
Consequently there may be several documents in the open source project that describe coding standards.
 +
These documents need to be checked beforehand for consistency.
 +
For instance in OpenMRS, see https://wiki.openmrs.org/display/docs/Code+Style and https://wiki.openmrs.org/display/docs/Coding+Conventions.
  
 
What are some likely difficulties that an instructor may encounter using this activity?
 
What are some likely difficulties that an instructor may encounter using this activity?
  
  
=== Additional Information: ===
+
=== Additional Information ===
{| border="1"
+
{| class="wikitable"
 
|-  
 
|-  
|'''ACM Knowledge Area/Knowledge Unit''' || What ACM Computing Curricula 2013 knowledge area and units does this activity cover? [[ACM_Body_of_Knowledge]]
+
| '''ACM Knowledge Area/Knowledge Unit''' || What ACM Computing Curricula 2013 knowledge area and units does this activity cover? [[ACM_Body_of_Knowledge]]
 
|-
 
|-
|'''ACM Topic''' || What specific topics are addressed? The Computing Curriucula 2013 provides a list of topics - https://www.acm.org/education/CS2013-final-report.pdf
+
| '''ACM Topic''' || What specific topics are addressed? The Computing Curriucula 2013 provides a list of topics - https://www.acm.org/education/CS2013-final-report.pdf
 
|-
 
|-
|'''Level of Difficulty''' || Is this activity easy, medium or challenging?  
+
| '''Level of Difficulty''' || Is this activity easy, medium or challenging?  
 
|-
 
|-
|'''Estimated Time to Completion''' ||  How long should it take for the student to complete the activity?
+
| '''Estimated Time to Completion''' ||  How long should it take for the student to complete the activity?
 
|-
 
|-
|'''Materials/Environment''' || What does the student need?  Internet access, IRC client, Git Hub account, LINUX machine, etc.?
+
| '''Materials/Environment''' || What does the student need?  Internet access, IRC client, Git Hub account, LINUX machine, etc.?
 
|-
 
|-
|'''Author''' || Who wrote this activity?
+
| '''Author(s)''' || Dale Skrien, Janet Davis
 
|-
 
|-
|'''Source''' || Is there another activity on which this activity is based?  If so, please provide a link to the original resource.
+
| '''Source''' || Is there another activity on which this activity is based?  If so, please provide a link to the original resource.
 
|-
 
|-
|'''License''' || Under which license is this material made available? (http://creativecommons.org/licenses/)
+
| '''License''' || Under which license is this material made available? (http://creativecommons.org/licenses/)
 
|}
 
|}
  
=== Suggestions for Open Source Community: ===
+
=== Suggestions for Open Source Community ===
 
Suggestions for an open source community member who is working in conjunction with the instructor.
 
Suggestions for an open source community member who is working in conjunction with the instructor.
  
Line 139: Line 144:
 
[[File:CC_license.png]]
 
[[File:CC_license.png]]
  
[[Category: Learning_Activity]]
+
[[Category:Learning Activity]]
[[Category: LEARNING_ACTIVITY_SUBCATEGORY]]
+
[[Category:Coding and Style]]
 +
[[Category:CS1]]
 +
[[Category:CS2]]
 +
[[Category:OpenMRS]]
 +
[[Category:Good Draft]]

Revision as of 17:59, 8 March 2017


Title Review Coding Conventions
Overview Students review 1 or more samples of code to see how close sample(s) are to the HFOSS project coding conventions
Prerequisite Knowledge Knowledge of the programming language for the HFOSS project to a level necessary to understand the coding conventions
Learning Objectives Read and understand coding conventions for a large project; use standards to critique existing code; (optional) critique coding conventions

Background

XKCD: Code Quality 2

More detail on prerequisite knowledge? For the OpenMRS coding conventions, students will need a CS2-level understanding of Java, including exception handling.

Is there background reading material? The coding conventions used by the project. For example, see OpenMRS Code Style and OpenMRS Coding Conventions

Are there other activities the student should have done first? No.

What is the rationale for this activity? Why are the learning objectives important? Students need practice reading other people's code. Students should appreciate the need for coding conventions, and seeing code where conventions are not applied is a good way to learn their value. If students are going to write code in an HFOSS project, they need to be able to apply the project's coding conventions themselves. Students may later contribute to the HFOSS project by revising the code so that it adheres to the coding conventions.

Include helpful hints to faculty here.

  • OpenMRS Coding Conventions refer to Eclipse's automatic formatting. There is a separate, older OpenMRS Code Style which the Coding Conventions page does not refer to. Are they both current? Someone should ask on the Developers email list.
  • More generally, you may have to do some exploration of your project's coding conventions to find how current they are, if they are all in one document, what tools developers are expected to use, etc.
  • The instructor should choose code modules carefully to illustrate coding conventions at an appropriate level for their students (e.g., formatting vs exception handling). The project community may be able to help identify appropriate modules to review.
  • For your class, is it important that this be a graded activity? Or could it be an ungraded, in-class activity?

Directions

What should the student do?

  1. Read code style and coding conventions.
  2. What questions do you have?
  3. Get code samples from the instructor.
  4. Get and follow the instructions from the instructor. For example, these might include:
    1. Identify as many violations as you can in each of the provided modules. (This is more of a homework assignment than a lab exercise, depending on the amount of code provided. Perhaps look at one module together in class, then students review others as homework.)
    2. Annotate each module by writing comments with the following information:
      1. Which convention is violated.
      2. What lines are affected. (Write your comment at the first affected line of code if it spans multiple lines.)
      3. How the code violates the convention. Explain in 1-3 complete sentences (usually 1).
    3. Rank modules from most violations to least violations.
    4. What conventions seem to be most frequently violated? Put yourself in the mind of the programmer: Why might these conventions be difficult to follow?
    5. Did you find any violations that would potentially result in an error or crash or incorrect behavior? If so, which one(s)?
    6. In class, compare your answers. Do you agree? If you disagree, what are your reasons?

Possible extensions:

  1. Reflect: What did you find confusing about the code style guidelines or coding conventions?
  2. Reflect: What style guidelines have you learned in other contexts that were not part of the project's conventions?

Deliverables

What will the student hand in? Annotated code is one possibility. Alternatively, using a template supplied, students will turn in written analysis of the code sample.

Assessment

How will the activity be graded?

How will learning will be measured?

Include sample assessment questions/rubrics.

Criteria Level 1 (fail) Level 2 (pass) Level 3 (good) Level 4 (exceptional)
How many violations did you identify?
Did you provide the required information for each violation?
Did you accurately apply the project's conventions?
Did you adequately explain how the code violates the convention?


Comments

What should the instructor know before using this activity?

Documentation for open source projects is often not well organized or maintained. Consequently there may be several documents in the open source project that describe coding standards. These documents need to be checked beforehand for consistency. For instance in OpenMRS, see https://wiki.openmrs.org/display/docs/Code+Style and https://wiki.openmrs.org/display/docs/Coding+Conventions.

What are some likely difficulties that an instructor may encounter using this activity?


Additional Information

ACM Knowledge Area/Knowledge Unit What ACM Computing Curricula 2013 knowledge area and units does this activity cover? ACM_Body_of_Knowledge
ACM Topic What specific topics are addressed? The Computing Curriucula 2013 provides a list of topics - https://www.acm.org/education/CS2013-final-report.pdf
Level of Difficulty Is this activity easy, medium or challenging?
Estimated Time to Completion How long should it take for the student to complete the activity?
Materials/Environment What does the student need? Internet access, IRC client, Git Hub account, LINUX machine, etc.?
Author(s) Dale Skrien, Janet Davis
Source Is there another activity on which this activity is based? If so, please provide a link to the original resource.
License Under which license is this material made available? (http://creativecommons.org/licenses/)

Suggestions for Open Source Community

Suggestions for an open source community member who is working in conjunction with the instructor.



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

CC license.png

Personal tools
Namespaces
Variants
Actions
Events
Learning Resources
HFOSS Projects
Evaluation
Navigation
Toolbox