Intro to Style Guides (Activity)

From Foss2Serve
(Difference between revisions)
Jump to: navigation, search
(Suggestions for the Open Source Project:)
 
(14 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
__NOTOC__
 
__NOTOC__
{| border="1"
 
|-
 
|'''Title''' || The Need for Style Guides
 
|-
 
|'''Overview''' || In this activity you 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, you will develop a style guide for your team.
 
|-
 
|'''Prerequisite Knowledge''' || What topics and tools does the student need to know prior to beginning this activity?
 
|-
 
|'''Learning Objectives''' || Upon completion of this activity, you will be able to:
 
  
 +
{{Learning Activity Overview
 +
|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.
 +
|prerequisites=
 +
Knowledge of basic regular expressions is helpful to understand the checkstyle documentation.
 +
|objectives=
 
* 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.
|}
+
|process skills=
 +
}}
  
=== Background: ===
+
=== Background ===
Is there background reading material?
+
  
Are there other activities the student should have done first?
+
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. 
  
What is the rational for this activity?
+
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.
  
Include helpful hints to faculty here.
+
=== Directions ===
  
=== Directions: ===
+
The following activities should be completed by the student before coming to class:
  
In-class activity:
+
* (30 minutes) This article talks about the need for a coding standard
 +
** http://www.smashingmagazine.com/2012/10/25/why-coding-style-matters/
 +
* (60 minutes) In this video, Crockford uses JavaScript to illustrate key ideas about programming style
 +
** https://www.youtube.com/watch?v=_EANG8ZZbRs
 +
* (30 minutes) Read about the Google Style Guide
 +
** https://google-styleguide.googlecode.com/svn/trunk/javaguide.html
 +
* (optional 15 minutes) Read this article about style versus standards
 +
** http://www.jrtwine.com/Articles/CodingStyles/CStyle1.htm
 +
* (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.
  
* look at three versions of the same code
+
Ideas for in-class activities:
** which do you like best?  worst?  why?
+
* discuss consistency of code
+
  
 +
* Some checkstyle items are controversial, providing an opportunity for lively debate.  See items in the following categories
 +
** Metrics: http://checkstyle.sourceforge.net/config_metrics.html
 +
** Size Violations: http://checkstyle.sourceforge.net/config_sizes.html
 +
** Coding: http://checkstyle.sourceforge.net/config_coding.html
  
=== Deliverables: ===
+
* Have students work in their groups to compare their assessment of the checkstyle items.  Each group should develop a single style for their work.
What will the student hand in?
+
  
=== Assessment: ===
+
(optional) Install checkstyle for your favorite IDE:
How will the activity be graded?
+
* http://checkstyle.sourceforge.net/index.html#Related_Tools
+
How will learning will be measured?
+
  
Include sample assessment questions/rubrics.
+
(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
  
=== Comments: ===
+
=== Deliverables ===
What should the instructor know before using this activity?
+
  
What are some likely difficulties that an instructor may encounter using this activity?
+
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
  
=== Additional Information: ===
+
=== Assessment ===
{| border="1"
+
|-
+
|'''Knowledge Area/Knowledge Unit''' || What ACM Computing Curricula 2013 https://www.acm.org/education/CS2013-final-report.pdf knowledge area and units does this activity cover?
+
|-
+
|'''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/)
+
|}
+
  
 +
TBD
 +
 +
{{Learning Activity Info
 +
|acm unit=
 +
SE - Software Engineering
 +
|acm topic=
 +
SE/Software Process, SE/Tools and Environments,
 +
|difficulty=
 +
medium (because of the time required)
 +
|time=
 +
2.5 hours preparing plus one class session
 +
|environment=
 +
Internet access, Java IDE
 +
|author=
 +
Ben Coleman
 +
|source=
 +
|license=
 +
{{License CC BY SA}}
 +
}}
  
 
=== Suggestions for the Open Source Project: ===
 
=== Suggestions for the Open Source Project: ===
Line 72: Line 87:
  
  
--------------------
 
This work is licensed under a
 
[http://creativecommons.org/licenses/by-sa/4.0/ Creative Commons Attribution-ShareAlike 4.0 International License]
 
 
[[File:CC_license.png]]
 
  
[[Category: Learning_Activity]]
+
[[Category:Learning Activity]]
[[Category:Coding_and_Style]]
+
[[Category:Coding and Style]]
 +
[[Category:CS1]]
 +
[[Category:Good Draft]]

Latest revision as of 18:45, 8 March 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.

Prerequisites

Knowledge of basic regular expressions is helpful to understand the checkstyle documentation.

Learning
Objectives
After successfully completing this activity, the learner should be able to:
  • Explain how a style guide contributes to a team project.
  • Develop a style guide for a project.
Process Skills
Practiced


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:

Ideas for in-class activities:

  • 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.)

Deliverables

Ideas for assignments:

Assessment

TBD

ACM BoK
Area & Unit(s)

SE - Software Engineering

ACM BoK
Topic(s)

SE/Software Process, SE/Tools and Environments,

Difficulty

medium (because of the time required)

Estimated Time
to Complete

2.5 hours preparing plus one class session

Environment /
Materials

Internet access, Java IDE

Author(s)

Ben Coleman

Source
License

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

CC license.png


Suggestions for the Open Source Project:

Suggestions for an open source community member who is working in conjunction with the instructor.

Personal tools
Namespaces
Variants
Actions
Events
Learning Resources
HFOSS Projects
Evaluation
Navigation
Toolbox