Review Coding Conventions

From Foss2Serve
(Difference between revisions)
Jump to: navigation, search
 
(11 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 
__NOTOC__
 
__NOTOC__
−
{| border="1"
 
−
|-
 
−
|'''Title''' || Coding Conventions Review
 
−
|-
 
−
|'''Overview''' || Students review 1 or more samples of code to see how close sample(s) are to the HFOSS coding conventions
 
−
|-
 
−
|'''Prerequisite Knowledge''' || Knowledge of the programming language for the project to a level necessary to understand the coding conventions
 
−
|-
 
−
|'''Learning Objectives''' || What should the student be able to do after completing this activity?
 
−
|}
 
  
−
=== Background: ===
+
{{Learning Activity Overview
−
Is there background reading material?
+
|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
 +
|prerequisites=
 +
Knowledge of the programming language for the HFOSS project to a level necessary to understand the coding conventions.
 +
|objectives=
 +
* Read and understand coding conventions for a large project.
 +
* Use standards to critique existing code; (optional) critique coding conventions
 +
|process skills=
 +
}}
  
−
Are there other activities the student should have done first?
+
=== Background ===
  
−
What is the rationale for this activity?
+
[http://xkcd.com/1695/ XKCD: Code Quality 2]
  
−
Include helpful hints to faculty here.
+
'''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
 +
[https://wiki.openmrs.org/display/docs/Code+Style OpenMRS Code Style] and
 +
[https://wiki.openmrs.org/display/docs/Coding+Conventions OpenMRS Coding Conventions]
  
−
=== Directions: ===
+
'''Are there other activities the student should have done first?''' No.
−
What should the student do?
+
  
 +
'''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.
  
−
=== Deliverables: ===
+
'''Include helpful hints to faculty here.'''
−
What will the student hand in?
+
* [https://wiki.openmrs.org/display/docs/Coding+Conventions OpenMRS Coding Conventions] refer to Eclipse's automatic formatting. There is a separate, older [https://wiki.openmrs.org/display/docs/Code+Style 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?'''
  
−
=== Assessment: ===
+
# Read code style and coding conventions.
−
How will the activity be graded?
+
# What questions do you have?
−
+
# Get code samples from the instructor.
−
How will learning will be measured?
+
# 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.)
 +
## Annotate each module by writing comments with the following information:
 +
### Which convention is violated.
 +
### What lines are affected. (Write your comment at the first affected line of code if it spans multiple lines.)
 +
### How the code violates the convention. Explain in 1-3 complete sentences (usually 1).
 +
## Rank modules from most violations to least violations.
 +
## What conventions seem to be most frequently violated? Put yourself in the mind of the programmer: Why might these conventions be difficult to follow?
 +
## 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?
  
−
Include sample assessment questions/rubrics.
+
'''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?
  
−
{| border="1" class="wikitable"
+
=== 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.''
 +
 
 +
{| class="wikitable"
 
! Criteria
 
! Criteria
 
! Level 1 (fail)
 
! Level 1 (fail)
Line 43: Line 73:
 
! Level 4 (exceptional)
 
! Level 4 (exceptional)
 
|-
 
|-
−
| '''The purpose of the project'''
+
| '''How many violations did you identify?'''
 
|  
 
|  
 
|  
 
|  
Line 50: Line 80:
  
 
|-
 
|-
−
| '''Why the project is open source'''
+
| '''Did you provide the required information for each violation?'''
 
|  
 
|  
 
|  
 
|  
Line 56: Line 86:
 
|  
 
|  
  
−
|}
+
|-
 +
| '''Did you accurately apply the project's conventions?'''
 +
|
 +
|
 +
|
 +
|
  
−
=== Comments: ===
+
|-
−
What should the instructor know before using this activity?
+
| '''Did you adequately explain how the code violates the convention?'''
 +
|
 +
|
 +
|
 +
|
  
−
What are some likely difficulties that an instructor may encounter using this activity?
 
  
−
 
−
=== Additional Information: ===
 
−
{| border="1"
 
−
|-
 
−
|'''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: ===
+
=== Comments ===
−
Suggestions for an open source community member who is working in conjunction with the instructor.
+
* ''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 ===
  
−
--------------------
+
{{Learning Activity Info
−
This work is licensed under a
+
|acm unit=
−
[http://creativecommons.org/licenses/by-sa/4.0/ Creative Commons Attribution-ShareAlike 4.0 International License]
+
|acm topic=
 +
|difficulty=
 +
|time=
 +
|environment=
 +
Internet access, IRC client, Git Hub account, LINUX machine, etc.?
 +
|author=
 +
Dale Skrien, Janet Davis
 +
|source=
 +
|license=
 +
{{License CC BY SA}}
 +
}}
  
−
[[File:CC_license.png]]
+
=== Suggestions for Open Source Community ===
 +
* ''Suggestions for an open source community member who is working in conjunction with the instructor.''
  
−
[[Category: Learning_Activity]]
+
[[Category:Learning Activity]]
−
[[Category: LEARNING_ACTIVITY_SUBCATEGORY]]
+
[[Category:Coding and Style]]
 +
[[Category:CS1]]
 +
[[Category:CS2]]
 +
[[Category:OpenMRS]]
 +
[[Category:Good Draft]]

Latest revision as of 12:02, 8 September 2018


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

Prerequisites

Knowledge of the programming language for the HFOSS project to a level necessary to understand the coding conventions.

Learning
Objectives 		After successfully completing this activity, the learner should be able to:
  • Read and understand coding conventions for a large project.
  • Use standards to critique existing code; (optional) critique coding conventions
Process Skills
Practiced


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 BoK
Area & Unit(s)
ACM BoK
Topic(s)
Difficulty
Estimated Time
to Complete
Environment /
Materials

Internet access, IRC client, Git Hub account, LINUX machine, etc.?

Author(s)

Dale Skrien, Janet Davis

Source
License

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

CC license.png


Suggestions for Open Source Community

  • Suggestions for an open source community member who is working in conjunction with the instructor.
Retrieved from "http://foss2serve.org/index.php?title=Review_Coding_Conventions&oldid=12672"
Personal tools
Namespaces
Variants
Actions
Events
Learning Resources
HFOSS Projects
Evaluation
Navigation
Toolbox