# QA Reference Guide:

### Questions to ask in planning meetings

* How are you planning on dividing work over the three weeks?
* Is your division of work balanced over the weeks?
* Do you have any prior commitments that might affect this timeline?
* Do you expect a varrying amount of research needed for these different parts?
* Would another order of development benefit the other teams to give feedback earlier?
* What type of dependencies would this project require?
* Are there system limitations that might be an issue?
* What amount of non-trivial code is required for for you to be writing?
* What amount of non-trivial code is required for comprehension of the topics involed?
* What amount of non-trivial code is required for users to implement the demo themselves?
* Is there any overlap or re-usable code from other projects?
* Which portions of the project are code examples and which are to run behind the scenes?

### Questions to ask in Code Review

* Does the compiler give you any warnings? Would the audience be worried seeing these?
* Do your variable names make sense for your program?
* Do your function names accurately describe what you're doing?
* Can you consolidate any of the smaller pieces into a still simple function/class?
* Can you split an involved chunk of code into simple pieces without losing meaning?
* How many distinct control flows are going through your code? Can this be reduced?
* Does your code match a style guide / have you used a linter?
* http://google.github.io/styleguide/ is a good jumping off point
* Have you made sure there's no passwords or API keys being posted online?

## How to Check for Comprehensive Explanations.

##### Reflexive clauses are your friends

### **Content**

It is each individual's job to make sure that their own code snippets are formatted and commented correctly—this is in terms of the functionality of the code. If the code works, but the spacing is off, this must be fixed by the developer themselves most likely during their second revision, but **before** merging.

1. [ ] The code is functional and devoid of errors
* [ ] If you can think of a case where the code fails, this must be addressed
2. [ ] The code uses the correct implementation
* [ ] If the lab is about DFS, the solution should involve DFS
* [ ] Adheres to DRY principle
3. [ ] The code uses syntax that is correct and does not contain too many "shortcuts"
* [ ] If shortcuts are used, please make sure that this has proper explanation (really only applies to Python)
* [ ] No extraneous punctuation marks. Ex: a lot of people code primarily in C/C++/Java for school in which semicolons are mandatory, if some of these show up in Python, they should be removed
4. [ ] Aesthetic and easy to read. Passes linting.
* [ ] Semantically named variables
* [ ] Comments are preceded by a space. Ex: `// this is a correct comment`
* [ ] Spaces between operators. Ex: `snake = 'Voldemort'`
* [ ] Not `snake='Voldemort'`, `snake ='Voldemort'`, or `snake= 'Voldemort'`
* [ ] Has proper language selected on code block so that there is helpful highlighting

### **Context**

#### Reminders

* [ ] Are reminders given when necessary? At times we have to remind students of how an algorithm works
* [ ] Usually at the beginning of the **first** mention in the document

#### Clear and Comprehensive Explanations

##### Methods \(overview\)

* [ ] Arguments
* [ ] Why are those our arguments?
* [ ] What is the expected type and data of each argument
* [ ] Pass by reference or pass by value
* [ ] Returns
* [ ] \(Base\) Cases
* [ ] Explain the condition
* [ ] Explain the return
* [ ] Mention how we are going to return the correct value in switch cases, if else statements, recursion, etc

##### Methods \(body\)

* [ ] Conditionals
* [ ] Explain why we check against the values that we do—is it mandated by the algorithm, the length of a list, etc
* [ ] Explain the purpose of each conditional—is it to return the correct value, change a value, simply finding an element in a linked list, etc
* [ ] Explain all temporary variables if used

##### Language

* [ ] Use technical terms when possible
* [ ] The **first instances** of these in each document are bolded and followed by a reminder or an explanation
* [ ] **Reflexive clauses** are your friends
* [ ] If you use non technical terms \(ex: left or right\), please have them be accompanied by **more** technical terms \(ex: less than, greater than\)
* [ ] Be careful that your tone does not become too dry—we still want to sound personable and engaging
* [ ] Adding more adjectives and adverbs do not make your explanations more clear. Just because an explanation is prefaced by "simply" or any other similar word, it does not mean that the explanation is that.
* [ ] Adding more exclamation points is borderline patronizing—babying almost. Engaging and simple introductions can be written without more than 2 exclamation points.

### **Ordering**

* [ ] Is the order of the information relevant? You want to minimize the usage of the words "this will be discussed later"
* [ ] Is it discussed in a way where each topic builds upon on the next one?
* [ ] Is this the most common way for this thing to be explained? Can rearranging the order better explain this thing?

### **Visuals**

* [ ] Visuals are not off topic and provide contextual value
* [ ] Is a screenshot of the expected format informative for students to make sure that they are on track? Ex: inputs & expected outputs
* [ ] Is the image properly explained? (If applicable) Ex: if the image is a diagram of BFS, please "walk through" the image.
* [ ] Images have a description/alternative text