Review Coding Conventions

Revision as of 15:50, 17 June 2016

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.

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:

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