Project Documents

asking_for_help.md

How to Ask Questions on Github

In order to receive help on an issue you are having during your development process you must submit a Github Issue for your project. Below is a guide for the information that must be included when submitting an issue. It is expected that you will try to debug/solve an issue prior to submitting a request for help on Github.

Context

When submitting an issue provide some context as to what the problem is. This includes but is not limited to:

• What User Story you are currently working on
• What you are trying to do
• Detailed description of the bug or error
• Relevant code/files/errors, screenshots
• Gems and/or other technologies being used

What have you tried?

Give information about what you have done to solve the problem. Including but not limited to:

• Documentation you have looked at
• Steps you have taken to solve the problem
• Resources you have used

Question

What would you like help with specifically?

For an example: how to ask questions

code_quality_guide.md

HAMstache Guidelines

Your guide to writing good code

S -> Small

• Methods should be small and concise
  • No more than 10-15 lines of code for each method
  • Methods should have one, clearly defined function that is readily apparent
• Classes should follow the Single Responsibility Principle
  • All classes should have a single concern and contain only methods related to the manipulation of the objects it creates.

T -> Tested

• Red
  • Write tests and watch them fail
• Green
  • Write just enough code to make the tests pass
• Refactor
  • Look at your code for areas of potential refactoring
    • Repeated code
    • More efficient design
• Run your tests to ensure that the refactor was successful.
• WRITE MORE TESTS

A -> Arid

D on't R epeat Y ourself! To keep your code DRY abstract areas of repeated code into methods.

C -> Commented

• Use comments to clarify code whose function is not obvious
• Use comments to indicate discrete sections of code
• Use comments to indicate areas of code that need further attention
• Use comments sparingly
  • Avoid over-commenting
  • Your code should be written in such a fashion that it explains itself.

H -> Hugs and High-Fives!

E -> Easy-to-Read

• Lines of code should not extend beyond 80 characters to maintain readability.
• Mainting proper indentation and whitespace throughout your code.
  • Always indent 1 tab (2 spaces) when nesting lines of code.
  • Single line of whitespace between method definitions
• Name variables semantically for the data they represent
• Use CamelCase for classes
• Use snake_case for variable and method names

code_review_guidelines.md

Code Reviews

What is code review?

Code review is any process where people review code that has already been written. Generally this is to identify errors or to suggest ways the code could be improved (refactored).

Why do code reviews?

Jeff Atwood (co-founder of Stack Exchange, and a smart dude) has written a great summary which I encourage you to read. The short verion? Code review can reduce the number of errors in our programs dramatically.

In addition HAMco believes that learning to read code critically is an important part of improving our own code. After all, to improve our own code, we must read it, looking for ways to improve it.

Additionally, many work environments practice some form of code review, so it's good to get practice in giving feedback to others now. Even if your future workplaces don't have a formal code review process, you may find them so helpful that you implement your own informal practices with your teammates!

How to Code Review?

At it's core, doing a code review is just reading code and giving feedback. When reading code, you should be looking for:

• code quality (hamSTACHE)
• potential bugs

When giving (and recieving) feedback, remember that we're discussing and commenting on code, not the person who wrote it!

There are a few ways we can actually read the code and give feedback:

Read The Most Recent Version (Full-Context)

One way is to just read through the most recent version of the codebase. (i.e. use Atom to browse the code.) Give feedback as you're reading to the person or by leaving comments in the code.

This can be a lot of code, so it's generally a good idea to only focus on a few areas of the codebase in this case. (i.e. a few models or controllers.)

Read What's Changed (Diff)

Another way is to review just the code that's changed since you last reviewed, and give feedback on that.

Github will show you the changes between any two branches, commits, etc, including by time!

To see this view, use a URL like: https://github.com///compare/master@{1day}

This will show the difference between the current master branch (implied), and the master branch 1 day ago. Make sure to select the appropriate time frame.

p1_presentation_guidelines.md

WDI June 2014 - Closure

Project 1 Presentations

Tuesday, July 15, 2014

Description

We will take Tuesday to pause our work on our projects and share where we are at with the rest of the class. Remember, this is not the last time you will work on your project.

Format

• Project presentations should be 10 minutes long + 5 minutes for questions. That is not much time, so make sure to streamline your presentations.
• You will be able to hook up to the projector to demo your project and show us code. You are not required to have a slide deck for the rest of your presentation.
• Ensure that your up-to-date application is deployed to Heroku
• Ensure that your Trello board is up to date
• Ensure that your README is complete
• During presentations, your laptop should not be open, unless you are on deck to present.
• You are granted two questions for the entirety of the presentations. This is because we have to stick to a very tight time schedule, so use your questions wisely!

Section	Description
Demo	A short (1 min) demonstration of the key features of your application
Creativity	Show us one thing that you are proud of (let's see the code!)
Discernment	Tell us about one thing that did not go well (how did you handle it?)
Follow-up	What are your next steps for this project?

Order of presentations

Morning

• Francis
• Alexander
• Liza
• Alexandra
• SeanJ
• Eric
• Fen
• Albert
• Michael
• Hoa
• Najee

Afternoon

• Patrick
• Khadijah
• Jon
• Elizabeth
• SeanT
• Peter
• Sarit
• Ranjan
• Christiana
• Charlye
• Gadi

p1_refactoring_guidelines.md

Refactoring Project 1

Before You Begin

Push the lastest copy of your project to GitHub, so we can give you the most accurate feedback possible.

Pair Refactoring Excercise

For this exercise, we will be refactoring our first projects. You should NOT add any features. Instead, you should just focus on improving code quality. Refer to the hamSTACHE guidelines. VERY MINOR changes in functionality are acceptable if they are required to make an improvement in code quality.

We will refactor our projects by pair programming with a partner.

You can use any pair programming technique / style that you'd like, including:

• Driver/Navigator
• Ping/Pong (A Write tests, B makes them pass, repeat)
• Ping/Pong Alternating (A Write tests, B makes them pass, then flip)

Note: Just because you're working on A's project, doesn't mean A has to be the driver for driver/navigator.

You have until 5:00pm, and you should spend equal amounts of time on your project and your partner's. You may divide this time however you like, i.e. you can do 1 hour blocks alternating between projects, or you can do 3 hour blocks.

Pairing Teams

• Albert / Hoa
• Alexander / Christiana
• Alexandra / Sarit
• Charlye / Michael
• Christiana / Alexander
• Elizabeth / SeanT
• Eric / Francis
• Fen / Patrick
• Francis / Eric
• Gadi / Jon
• Hoa / Albert
• Jon / Gadi
• Khadijah / Peter
• Liza / Najee
• Michael / Charlye
• Najee / Liza
• Patrick / Fen
• Peter / Khadijah
• Ranjan / SeanJ
• Sarit / Alexandra
• SeanJ / Ranjan
• SeanT / Elizabeth

p1_requirements.md

WDI June 2014 - Closure

Project 1

Tuesday, July 8 - Monday, July 14

Learning Goals

• Build confidence as a developer
• Develop a moderately complex web application with a focus on code quality and best practices
• Utilize AGILE development techniques
• Implement a new technology through reading documentation and source code.
• Establish a healthy and maintainable development workflow
• Learn how to ask for help from other developers

Requirements

• Rails app with a PostgreSQL database
• At least 3 models
  • ActiveRecord Models
    • At least one relationship (one-to-many, many-to-many, etc.)
  • API wrapper Models
• Implement a new technology (gem or API) not explicitly covered in class.
• User Stories
  • Tracked using Trello or Pivotal Tracker
• Attendance at daily SCRUM
• Daily code review with a partner
• Submit Github issues for asking questions
  • see document in the Project 1 folder
• Hosted on Heroku
  • Push to Heroku on day 1 when you create your Rails app
• Documentation
  • A README containing a conceptual overview of the project
  • A link to your up-to-date User Stories
  • A link to your up-to-date ERD
  • A link to the Heroku-hosted site

No JavaScript or CSS Frameworks (Bootstrap, Foundation, etc.)

Don't forget to add all 3 instructors as collaborators on:

• Your project's GitHub repository
• Your user stories board (eg. Trello)
• Your ERD (if you're using software such as LucidChart)

p2_requirements.md

Closure - WDI Class, June 2014

Project 2

Objectives

• Work with other developers on a common code base
• Manage team interactions in a collaborative software development environment
• Build a complex project involving asynchronous data exchange between the front-end and back-end
• Ensure code quality and adherence to a consistent code style
• Present your work effectively in both presentational and technical environments

Objective-based Deliverables

Work with other developers on a common code base

• Utilize git branches and pull requests to contribute to a common code base
• Scrum at least once a day (morning scrum required)
• Divide work logically to minimize merge conflicts
• Effectively resolve merge conflicts that may arise during collaborative software development

Manage team interactions in a collaborative software development environment

• Communicate effectively with team members
• Separate personal and professional concerns

Build a complex project involving asynchronous data exchange between the front-end and back-end

• Rails application with at least 3 models
• User authentication
• Utilize AJAX to perform asynchronous data exchange between client and server

Ensure code quality and adherence to a consistent code style

• Small
• Tested
• Arid (DRY)
• Commented
• Hugs/High Fives
• Easy-to-read (semantic naming)

Present your work effectively in both presentational and technical environments

• In-class group presentations of project
• Project 'Science fair'

p3_requirements.md

Project 3 Requirements

Objectives

• Build a complex project involving asynchronous data exchange
• Ensure code quality and adherence to a consistent code style
• Present your work effectively in both presentational and technical environments
• Build a tested, secure web application that is deployed to a remote server
• Agile software development

Guidelines

• Your app must be deployed and running on Heroku at the end of this project sprint.

• Your app must be tested (coverage of 80% or greater).

  • Unit testing of models (rspec)
  • Acceptance testing (capybara)
  • Front-End testing (jasmine)

• Your app must adhere to the guidelines of HAMstache

• You must be able to defend all decisions made in the development of your application regarding implementation, technologies used, etc.

  • Front-End frameworks utilized (JavaScript, CSS)
  • Back-End implementation
  • Gems/Libraries included

• You must have complete User Stories, ERDs and documentation for your project.