Review Coding Conventions

(Difference between revisions)
Jump to: navigation, search
(Copied from TitanPad - Added rubric questions)
Line 14: Line 14:
  
 
[http://xkcd.com/1695/ XKCD: Code Quality 2]
 
[http://xkcd.com/1695/ XKCD: Code Quality 2]
 
 
'''More detail on prerequisite knowledge?'''
 
'''More detail on prerequisite knowledge?'''
 
For the OpenMRS coding conventions, students will need a CS2-level understanding of Java, including exception handling.
 
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  
 
'''Is there background reading material?'''  The coding conventions used by the project.  For example, see  
[https://wiki.openmrs.org/display/docs/Code+Style OpenMRS Code Style]
+
[https://wiki.openmrs.org/display/docs/Code+Style OpenMRS Code Style] and
 
[https://wiki.openmrs.org/display/docs/Coding+Conventions OpenMRS Coding Conventions]
 
[https://wiki.openmrs.org/display/docs/Coding+Conventions OpenMRS Coding Conventions]
  
 
'''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 by revising 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 30: Line 29:
 
* 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.
 
* 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.
 
* 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: ===
 
=== Directions: ===
Line 37: Line 37:
 
# What questions do you have?
 
# What questions do you have?
 
# Get code samples from the instructor.
 
# Get code samples from the instructor.
# Get rubric from the instructor.  For example, it might include:
+
# Get and follow the instructions from the instructor.  For example, these might include:
 
## 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.)
 
## 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.)
 
## Annotate each module by writing comments with the following information:
 
## Annotate each module by writing comments with the following information:
Line 47: Line 47:
 
## Did you find any violations that would potentially result in an error or crash or incorrect behavior? If so, which one(s)?
 
## Did you find any violations that would potentially result in an error or crash or incorrect behavior? If so, which one(s)?
 
## In class, compare your answers. Do you agree? If you disagree, what are your reasons?
 
## In class, compare your answers. Do you agree? If you disagree, what are your reasons?
 +
 +
'''Possible extensions:'''
 +
# Reflect: What did you find confusing about the code style guidelines or coding 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.
+
Annotated code is one possibility. Alternatively, using a template supplied, students will turn in written analysis of the code sample.  
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?'''
 
   
 
   
How will learning will be measured?
+
'''How will learning will be measured?'''
  
 
Include sample assessment questions/rubrics.
 
Include sample assessment questions/rubrics.
Line 67: Line 70:
 
! Level 4 (exceptional)
 
! Level 4 (exceptional)
 
|-
 
|-
| '''The purpose of the project'''
+
| '''How many violations did you identify?'''
 
|  
 
|  
 
|  
 
|  
Line 74: Line 77:
  
 
|-
 
|-
| '''Why the project is open source'''
+
| '''Did you provide the required information for each violation?'''
 +
|
 +
|
 +
|
 +
|
 +
 
 +
|-
 +
| '''Did you accurately apply the project's conventions?'''
 
|  
 
|  
 
|  
 
|  
Line 84: Line 94:
 
=== 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 consistently.  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?

Revision as of 15:48, 17 June 2016

Title Coding Conventions Review
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?

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 consistently. 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 Who wrote this activity?
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