Intro to Style Guides (Activity)
(Difference between revisions)
Dee.weikle (Talk | contribs) m (Added category) |
m |
||
| Line 1: | Line 1: | ||
__NOTOC__ | __NOTOC__ | ||
| − | {| | + | |
| + | {| class="wikitable" | ||
|- | |- | ||
| − | |'''Title''' || The Need for Style Guides | + | | '''Title''' || The Need for Style Guides |
|- | |- | ||
| − | |'''Overview''' || In this activity students will learn about why we need a style guide for team-based projects and compare style guides for a various projects. Based on this experience, students will develop a style guide for their team. | + | | '''Overview''' || In this activity students will learn about why we need a style guide for team-based projects and compare style guides for a various projects. Based on this experience, students will develop a style guide for their team. |
|- | |- | ||
| − | |'''Prerequisite Knowledge''' || Knowledge of basic regular expressions is helpful to understand the checkstyle documentation. | + | | '''Prerequisite Knowledge''' || Knowledge of basic regular expressions is helpful to understand the checkstyle documentation. |
|- | |- | ||
| − | |'''Learning Objectives''' || Upon completion of this activity, students will be able to: | + | | '''Learning Objectives''' || Upon completion of this activity, students will be able to: |
| − | + | ||
* Explain how a style guide contributes to a team project. | * Explain how a style guide contributes to a team project. | ||
* Develop a style guide for a project. | * Develop a style guide for a project. | ||
|} | |} | ||
| − | === Background | + | === Background === |
Working by themselves on small projects convinces students that coding style his little relevance. As they begin work on HFOSS projects, they need to begin to build an appreciation for the place of a standardized coding style. | Working by themselves on small projects convinces students that coding style his little relevance. As they begin work on HFOSS projects, they need to begin to build an appreciation for the place of a standardized coding style. | ||
| Line 20: | Line 20: | ||
This topic is an opportunity for active debate about coding style, but is also a lesson in the need for accepting standards - even if they are not your preference. | This topic is an opportunity for active debate about coding style, but is also a lesson in the need for accepting standards - even if they are not your preference. | ||
| − | === Directions | + | === Directions === |
The following activities should be completed by the student before coming to class: | The following activities should be completed by the student before coming to class: | ||
| Line 52: | Line 52: | ||
* gradle: https://docs.gradle.org/current/userguide/checkstyle_plugin.html | * gradle: https://docs.gradle.org/current/userguide/checkstyle_plugin.html | ||
| − | === Deliverables | + | === Deliverables === |
Ideas for assignments: | Ideas for assignments: | ||
| Line 61: | Line 61: | ||
** Sun style file: http://checkstyle.sourceforge.net/sun_style.html | ** Sun style file: http://checkstyle.sourceforge.net/sun_style.html | ||
| − | === Assessment | + | === Assessment === |
TBD | TBD | ||
| − | === Additional Information | + | === Additional Information === |
| − | {| | + | |
| + | {| class="wikitable" | ||
|- | |- | ||
| − | |'''Knowledge Area/Knowledge Unit''' || SE - Software Engineering | + | | '''Knowledge Area/Knowledge Unit''' || SE - Software Engineering |
|- | |- | ||
| − | |'''Topic''' || SE/Software Process, SE/Tools and Environments, | + | | '''Topic''' || SE/Software Process, SE/Tools and Environments, |
|- | |- | ||
| − | |'''Level of Difficulty''' || medium (because of the time required) | + | | '''Level of Difficulty''' || medium (because of the time required) |
|- | |- | ||
| − | |'''Estimated Time to Completion''' || 2.5 hours preparing plus one class session | + | | '''Estimated Time to Completion''' || 2.5 hours preparing plus one class session |
|- | |- | ||
| − | |'''Materials/Environment''' || Internet access, Java IDE | + | | '''Materials/Environment''' || Internet access, Java IDE |
|- | |- | ||
| − | |'''Author''' || Ben Coleman | + | | '''Author''' || Ben Coleman |
|- | |- | ||
| − | |'''Source''' || N/A | + | | '''Source''' || N/A |
|- | |- | ||
| − | |'''License''' || Creative Commons Attribution-ShareAlike 4.0 International License | + | | '''License''' || Creative Commons Attribution-ShareAlike 4.0 International License |
| + | |} | ||
Revision as of 19:32, 29 January 2017
| Title | The Need for Style Guides |
| Overview | In this activity students will learn about why we need a style guide for team-based projects and compare style guides for a various projects. Based on this experience, students will develop a style guide for their team. |
| Prerequisite Knowledge | Knowledge of basic regular expressions is helpful to understand the checkstyle documentation. |
| Learning Objectives | Upon completion of this activity, students will be able to:
|
Background
Working by themselves on small projects convinces students that coding style his little relevance. As they begin work on HFOSS projects, they need to begin to build an appreciation for the place of a standardized coding style.
This topic is an opportunity for active debate about coding style, but is also a lesson in the need for accepting standards - even if they are not your preference.
Directions
The following activities should be completed by the student before coming to class:
- (30 minutes) This article talks about the need for a coding standard
- (60 minutes) In this video, Crockford uses JavaScript to illustrate key ideas about programming style
- (30 minutes) Read about the Google Style Guide
- (optional 15 minutes) Read this article about style versus standards
- (90 minutes) Checkstyle (http://checkstyle.sourceforge.net/) is one of a number of static analysis tools that provides a measure of the health of a codebase.
- Read the ~150 items checked, and determine if each should be included or excluded from the standards for your group project. For each item included, state appropriate parameters.
Ideas for in-class activities:
- Some checkstyle items are controversial, providing an opportunity for lively debate. See items in the following categories
- Have students work in their groups to compare their assessment of the checkstyle items. Each group should develop a single style for their work.
(optional) Install checkstyle for your favorite IDE:
(optional) Add checkstyle to your build (ant, maven, etc.)
- ant: http://checkstyle.sourceforge.net/anttask.html
- maven: https://maven.apache.org/plugins/maven-checkstyle-plugin/
- gradle: https://docs.gradle.org/current/userguide/checkstyle_plugin.html
Deliverables
Ideas for assignments:
- A list of questions to answer as the student is reading the articles / watching the video
- A journal assignment (informal writing) where students respond to the arguments in the article / video
- Use the Google and/or Sun checkstyle files to see how well student's existing code meets the style
- Google style file: http://checkstyle.sourceforge.net/google_style.html
- Sun style file: http://checkstyle.sourceforge.net/sun_style.html
Assessment
TBD
Additional Information
| Knowledge Area/Knowledge Unit | SE - Software Engineering |
| Topic | SE/Software Process, SE/Tools and Environments, |
| Level of Difficulty | medium (because of the time required) |
| Estimated Time to Completion | 2.5 hours preparing plus one class session |
| Materials/Environment | Internet access, Java IDE |
| Author | Ben Coleman |
| Source | N/A |
| License | Creative Commons Attribution-ShareAlike 4.0 International License |
Suggestions for the Open Source Project:
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
