Code Base Understanding

(Difference between revisions)
Jump to: navigation, search
(Added content)
m (Evaluated for adoption readiness)
(5 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
__NOTOC__
 
__NOTOC__
{| border="1"
+
 
 +
{| class="wikitable"
 
|-  
 
|-  
|'''Title''' || Code Base understanding  
+
| '''Title''' || Code Base understanding  
 
|-
 
|-
|'''Overview''' || High level description of what the student will do Students will navigate a complex Java code base using a number of different techniques or strategies to understand the design and architecture.
+
| '''Overview''' || Students will navigate a complex Java code base using a number of different techniques or strategies to understand the design and architecture.
 +
|-
 +
| '''Prerequisite Knowledge''' || CS 2 - Data structures in Java
 
|-  
 
|-  
|'''Prerequisite Knowledge''' || CS 2- Data structures in Java
+
| '''Learning Objectives''' ||  
|'''Learning Objectives''' || What should the student be able to do after completing this activity?
+
 
The student should be able to:
 
The student should be able to:
 
Follow specific strategies to understand the code
 
Follow specific strategies to understand the code
Line 17: Line 19:
 
|}
 
|}
  
=== Background: ===
+
=== Background ===
 +
 
 
Is there background reading material?  
 
Is there background reading material?  
 
*Josh will add*
 
*Josh will add*
Line 28: Line 31:
  
  
What is the rationale for this activity? Students cannot become contributors to HFOSS projects until they understand the code base. This activity provides a number of strategies to help students approach a new code base and make sense of it. It has starting points (such as looking at unit testing) and more advanced techniques (such as using visualization tools to understand dependencies).
+
What is the rationale for this activity?  
 +
* Students cannot become contributors to HFOSS projects until they understand the code base. This activity provides a number of strategies to help students approach a new code base and make sense of it. It has starting points (such as looking at unit testing) and more advanced techniques (such as using visualization tools to understand dependencies).
  
 
Include helpful hints to faculty here.
 
Include helpful hints to faculty here.
 
Visualization tools for Java:
 
Visualization tools for Java:
Code City: https://marketplace.eclipse.org/content/codecity
+
* Code City: https://marketplace.eclipse.org/content/codecity
X-Ray: https://marketplace.eclipse.org/content/x-ray-software-visualization
+
* X-Ray: https://marketplace.eclipse.org/content/x-ray-software-visualization
JDeodorant https://marketplace.eclipse.org/content/jdeodorant
+
* JDeodorant: https://marketplace.eclipse.org/content/jdeodorant
  
 
This activity is designed for Eclipse.
 
This activity is designed for Eclipse.
 
Suggestion: have students work in groups
 
Suggestion: have students work in groups
  
Potential Problems in this activity:
+
=== Directions ===
code base changes
+
may not find what you are looking for - it may not contain unit tests, etc.
+
  
=== Directions: ===
+
* Look for unit tests, data model, high level classes, find something familiar, look at imports - are there packages the code is dependent upon?
What should the student do?
+
* Run unit tests
Look for unit tests, data model, high level classes, find something familiar, look at imports - are there packages the code is dependent upon
+
* Look for superclasses
Run unit tests
+
* From package dependencies figure out classes and package structure
Look for superclasses
+
From package dependencies figure out classes and package structure
+
  
 
Ordering where to look:
 
Ordering where to look:
Find any technical documentation (like JavaDoc) - keep it open to refer back to
+
* Find any technical documentation (like JavaDoc) - keep it open to refer back to
Look for a folder called testing and look for unit tests - if none exists then search junit in imports  
+
* Look for a folder called testing and look for unit tests - if none exists then search junit in imports  
What are the methods that are tested (hopefully there is documentation)? This identifies the core clases - these are classes of high interest
+
* What are the methods that are tested (hopefully there is documentation)? This identifies the core clases - these are classes of high interest
Run the unit tests
+
* Run the unit tests
Find the high level classes in the data model and the interfaces (in a game, the sprites, weapons, actors, etc. put another example here)
+
* Find the high level classes in the data model and the interfaces (in a game, the sprites, weapons, actors, etc. put another example here)
Use CodeCity and then X-Ray to visualize the code - what is most of the code dependent upon? Students should look at the code at the same time as they explore the visualization. This will help understand the class dependencies. (Ruby can expand on the criteria that can be used to visualize)
+
* Use CodeCity and then X-Ray to visualize the code - what is most of the code dependent upon? Students should look at the code at the same time as they explore the visualization. This will help understand the class dependencies. (Ruby can expand on the criteria that can be used to visualize)
Look at the import list to see if it is dependent upon other libraries
+
* Look at the import list to see if it is dependent upon other libraries
Find the data model, how is the data saved, what data structures are used?
+
* Find the data model, how is the data saved, what data structures are used?
JDeodorant could be used to help understand potential refactoring because it looks at bad part of the code
+
* JDeodorant could be used to help understand potential refactoring because it looks at bad part of the code
  
  
 +
=== Deliverables ===
  
=== Deliverables: ===
+
Submit answers to questions and screen captures
What will the student hand in?
+
Submit answers to quesitions and screen captures
+
 
Give instances of each of the bad smells from JDeodorant
 
Give instances of each of the bad smells from JDeodorant
 
Ultimate Goal: Make a code contribution back to the project with the enhancement.
 
Ultimate Goal: Make a code contribution back to the project with the enhancement.
  
=== Assessment: ===
+
=== Assessment ===
 +
 
 
How will the activity be graded?
 
How will the activity be graded?
 
   
 
   
Line 76: Line 76:
 
Include sample assessment questions/rubrics.
 
Include sample assessment questions/rubrics.
  
{| border="1" class="wikitable"
+
{| class="wikitable"
 
! Criteria
 
! Criteria
 
! Level 1 (fail)
 
! Level 1 (fail)
Line 98: Line 98:
 
|}
 
|}
  
=== Comments: ===
+
=== Comments ===
 +
 
 
What should the instructor know before using this activity?
 
What should the instructor know before using this activity?
  
 
What are some likely difficulties that an instructor may encounter using this activity?
 
What are some likely difficulties that an instructor may encounter using this activity?
  
 +
Potential problems in this activity may be if the underlying code base changes and/or that the student may not find what they are looking for (e.g., the project may not contain unit tests, etc.).
  
 
=== Additional Information: ===
 
=== Additional Information: ===
{| border="1"
+
{| class="wikitable"
 
|-  
 
|-  
|'''ACM Knowledge Area/Knowledge Unit''' || What ACM Computing Curricula 2013 knowledge area and units does this activity cover? [[ACM_Body_of_Knowledge]]
+
| '''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
+
| '''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?  
+
| '''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?
+
| '''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.?
+
| '''Materials/Environment''' || The student needs Internet access, IRC client, Git Hub account, LINUX machine, etc.?
 
|-
 
|-
|'''Author''' || Who wrote this activity? Ruby ElKharboutly, Josh Dehlinger, Ed Gehringer, Moshen Doroodchi, Lori Postner
+
| '''Author(s)''' || Ruby ElKharboutly, Josh Dehlinger, Ed Gehringer, Moshen Doroodchi, Lori Postner
 
|-
 
|-
 
|'''Source''' || Is there another activity on which this activity is based?  If so, please provide a link to the original resource.
 
|'''Source''' || Is there another activity on which this activity is based?  If so, please provide a link to the original resource.
Line 124: Line 126:
 
|}
 
|}
  
=== Suggestions for Open Source Community: ===
+
=== Suggestions for Open Source Community ===
 +
 
 
Suggestions for an open source community member who is working in conjunction with the instructor.
 
Suggestions for an open source community member who is working in conjunction with the instructor.
  
Line 134: Line 137:
 
[[File:CC_license.png]]
 
[[File:CC_license.png]]
  
[[Category: Learning_Activity]]
+
[[Category:Learning Activity]]
[[Category: LEARNING_ACTIVITY_SUBCATEGORY]]
+
[[Category:Coding and Style]]
 +
[[Category:Minimal Sketch]]
 +
 
 +
[[Category:CS2]]

Revision as of 17:18, 8 March 2017


Title Code Base understanding
Overview Students will navigate a complex Java code base using a number of different techniques or strategies to understand the design and architecture.
Prerequisite Knowledge CS 2 - Data structures in Java
Learning Objectives

The student should be able to: Follow specific strategies to understand the code Analyze the critical components of the code base Understand the importance of dependencies and coupling/decoupling Understand the importance of technical documentation in understanding the code Utilize visualization tools to navigate and understand complex codebase

Background

Is there background reading material?

  • Josh will add*

Are there other activities the student should have done first?

  • Read technical documentation specific to the project (project installation, tools needed, APIs) - assumption is that the environment is already installed
  • Run the program, understand the behavior of it

Come up with an enhancement - provides the motivation for this activity


What is the rationale for this activity?

  • Students cannot become contributors to HFOSS projects until they understand the code base. This activity provides a number of strategies to help students approach a new code base and make sense of it. It has starting points (such as looking at unit testing) and more advanced techniques (such as using visualization tools to understand dependencies).

Include helpful hints to faculty here. Visualization tools for Java:

This activity is designed for Eclipse. Suggestion: have students work in groups

Directions

  • Look for unit tests, data model, high level classes, find something familiar, look at imports - are there packages the code is dependent upon?
  • Run unit tests
  • Look for superclasses
  • From package dependencies figure out classes and package structure

Ordering where to look:

  • Find any technical documentation (like JavaDoc) - keep it open to refer back to
  • Look for a folder called testing and look for unit tests - if none exists then search junit in imports
  • What are the methods that are tested (hopefully there is documentation)? This identifies the core clases - these are classes of high interest
  • Run the unit tests
  • Find the high level classes in the data model and the interfaces (in a game, the sprites, weapons, actors, etc. put another example here)
  • Use CodeCity and then X-Ray to visualize the code - what is most of the code dependent upon? Students should look at the code at the same time as they explore the visualization. This will help understand the class dependencies. (Ruby can expand on the criteria that can be used to visualize)
  • Look at the import list to see if it is dependent upon other libraries
  • Find the data model, how is the data saved, what data structures are used?
  • JDeodorant could be used to help understand potential refactoring because it looks at bad part of the code


Deliverables

Submit answers to questions and screen captures Give instances of each of the bad smells from JDeodorant Ultimate Goal: Make a code contribution back to the project with the enhancement.

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?

Potential problems in this activity may be if the underlying code base changes and/or that the student may not find what they are looking for (e.g., the project may not contain unit tests, etc.).

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 The student needs Internet access, IRC client, Git Hub account, LINUX machine, etc.?
Author(s) Ruby ElKharboutly, Josh Dehlinger, Ed Gehringer, Moshen Doroodchi, Lori Postner
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

CC license.png

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