Review Coding Conventions

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 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 by revising 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.

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 rubric from the instructor. For example, it 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?

Deliverables:

What will the student hand in? Annotated code. 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)
The purpose of the project
Why the project is open source

Comments:

What should the instructor know before using this activity?

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