Expectations

This class is a little different from other classes and departments you are used to.

Learning Technology

Software development technologies change rapidly. In this class, we will be pointing you to existing resources to learn the details of a technology so that we can keep up to date. Thus, step-by-step instructions won’t be the norm for us. Instead, we encourage self-study and working with your group to get the technology to work for you. Plan around this, and know that we believe no time is wasted if you are learning a new technology.

Group Learning, Individual Work

In most collaborative classes, you may be used to “group work” where the team has one deliverable and everybody shares the load. In this class, we will have individual deliverables with a strong emphasis on feedback via code review. This means you will be looking at others’ code and even be graded on how good your feedback is.

Can I copy code from my group members? Mindlessly copying probably won’t work for you anyway, but it ok to discuss and get ideas from your partners work - even before their PR is due. Copying blindly is not allowed (and it is easy to spot and fail your submission!)
Can I work with people outside my group? You are always welcome to ask questions about interpreting the assignment to anyone. Debugging can be a gray area. At the day, your work needs to be your work. Remember, this class has practica in which you won’t be able to consult people for detailed help.
Can I post my code to GitHub? Career fair is coming you know. No you may not. Code is the most important deliverable in this class and we consider public posting your assignment work here a violation of academic integrity. We are fully aware that you want to find way to boost your GitHub profile for recruiters, and there are many ways other (better!) ways to do that.

Don’t Break the Build

No matter what. Seriously.

Every attempt should be made to keep the master branch running in your repository. Of course you’ll make mistakes, but we’ll be learning how to isolate those mistakes to separate branches in Git.

The way we do this is to use continuous integration (CI) with topic branches. For each iteration, you will be creating a separate branch in Git. You will continue to push your changes to this branch througout your work - probably often breaking your unit tests on the server. This is fine (it’s a work in progress, after all). As soon as you have created a branch, create a merge request on GitLab so that you can receive feedback. As you push to your branch, your merge request will be updated.

It Doesn’t Exist Unless It’s Pushed

In Git, you are not done after git commit - that is a local change. This does not count as submitted work. You must push for it to be considered pushed.

This is particularly important given academic integrity. Since you can easily change the local time on your machine and make the commit to backdate the work, we do not trust the “author date” field as when you worked on it. What we consider are the dates that GitLab shows as having received push and run the CI build.

Actionable Feedback

Providing solid feedback is important to us in this class.

Rude feedback is unhelpful. Be professional so you can be a useful colleague.
Positive feedback is nice, but only helpful when it’s specific. If you give a compliment, take an extra moment to be specific. This helps the other person anchor what they’re doing as good.
Suggest alternatives, but also be honest about any doubts you have on your own feedback. We’re all in this together.
Phrase things as softball questions, like “Would X be a better way because of Y?” as opposed to “You should do X.”

Here are few areas to look for in your feedback:

Is this easy to read?
Will this code be so good that it won’t need to change for a long time?
Will this code be easy to change if it needs to be?
Are the comments helpful? Concise? Non-redundant?
Is the formatting consistent and helpful?
Does this follow that technology community’s conventions? Take a look at the Code Review Checklist

In-class meetings. You will have weekly feedback meetings with your group members. Make sure to record discussions (pertinent ones) that you have with your cohort(s) in the merge request!. That way (a) the grader will have something to grade, and (b) it doesn’t get lost. I recommend saying “As discussed …” so that everyone knows what you’re talking about.

Style and Design Expectations

Each project will have coding style and design expectations. Be sure to review these in the project description. But, overall these over-arching principles are expected:

Stay DRY. As in, Don’t Repeat Yourself. If you find yourself repeating code a lot, your code wants to be reorganized or redesigned. It’s one of the single best indicators of design.
Avoid hard coded values. Make it easy to read and maintain. Use variables or well named contstants.
Organize your code and tests in such a way that people can find things easily.
Separate unit and function tests. Unit tests are atomic, sequence independent. Functional tests (many of the test scenarios are funtion level vs unit) are more complex, wich multiple steps. Make sure you know which is which!
Provide clear output for your tests. People need to know what is happening!
Have a clean separation between tests and production code. You should be able to deliver your product purely from your src folder and it should not have tests in it.
Use the packaging conventions of the language you are using (e.g. __init__.py and package.json)
The source tree should not have dependencies nor IDE config files in it, use .gitignore for this (e.g. node_modules should be ignored, .vscode)
The source tree should not have dependencies in it, use .gitignore for this (e.g. node_modules should be ignored)

Database Expectations

As a matter of security, you shall NEVER concatenate SQL query strings using user data. This is called a SQL injection vulnerability. Instead, use prepared statements with binding variables. Psycopg2 explains how to do this (as they say, not even at gunpoint). You’ll learn more about this in SWEN-331. Remember that Python has many ways of doing string interpolation.
A user of your API should never need to provide SQL. Think of it this way: your method signatures could conceivably be reimplemented by a totally different persistence system and nobody should be the wiser.
A user of your API should not need to know your schema to use this API. The method signatures should be abstract and domain-specific enough.
Obtaining primary keys should be easy. Consider how the APIs will actually be used. For example, return new primary keys whenever you insert something so that the user doesn’t have to do an additional search after they just created new records.
Always strive for readable, concise tests. Remember: your tests are the first thing the grader sees.
- Reduce boilerplate code. Make use of Python’s setup and teardown methods if necessary. Make test utility methods that make sense to you.
- ** Provide useful output (to the console) in your tests. Sometimes tests are complex, and need to show sequence. Sometimes you can’t tell if the test passed or failed. Make your test scenarios useful to the person reading the output!
- Iterate on your test data. As you come up with new test case ideas, you should also be updating your test data set.
Convention is to use SQL keywords in all caps and identifiers in snake_case. e.g. SELECT * FROM my_interesting_table