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.

System Expectations:

An important part of SW Engineering is understanding how components/ frameworks/ tools work and how to configure them. You will be required to learn how to install, use, configure multiple frameworks and tools that are part of creating applications. We will provide basic information, but you are expected to research and learn some of the subtleties of how components interact on your own personal system as part of your experience in this class.

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 frequently and even be graded on how good your feedback is.

  • Can I copy code from my group members? You will have different systems to work on, so mindlessly copying probably won’t work for you anyway. But, you are welcome (encouraged!) to look at the code of your teammates and use it as a reference for your own work - even before their PR is due.
  • 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.

Online and AI resources

Academic Integrity Policy including GPT

Original Student work

All student work is required to be their own. While we encourage research and reuse, all submissions must be your own, original creation. Copying/ Plagiarism is NOT tolerated. This is standard policy. This applies to ALL work, be it code related or written/ essay style submission.

Use of GPT/ AI

Again, all work is required to be your original creation. In situations where use of online resources is prohibited, this includes prohibition of GPT/ AI. In situations where it is not prohibited (unless otherwise stated), you may use online search for reference, but the output you create must be your own. This includes situations where you may use GPT or other AI tools for searching and/ or reference, with the following provisos:

If you use GPT (ChatGPT or other similar tools) you must also do the following: 1. Submit your prompts for GPT (as a separate file) as part of your work 2. Provide a confirming statement that GPT was used as reference only, and your work is original If ANY of your work is found to be copied (from online sources OR ChatGPT/ AI), you would be subject to serious penalties which could be one or more of the following: - Zero on the assignment - Zero on a full project - “F” on the course - Reported as plagiarism to the University and subsequent disciplinary action at the Institution level

In short – just don’t do it. It’s not worth the consequences to cheat (and it’s not ethical)!

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.”
  • We will provide a loose agenda for each lab meeting. Be sure to use it.

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?

In-class meetings. You will have weekly feedback meetings with your group members. We will be walking around to check on the discussion and stopping by each group for questions. If you are doing an in-person meeting, be sure to write down your feedback in a comment on 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 in class…” 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.
  • Unit tests are idempotent. You should be able to run your unit tests multiple times, and in any order, and not have them be impacted by side effects.
  • Unit tests are fast. They should run in under 1 minute. This does not count the time it takes the CI to fire up - it’s the time it takes for python -m unittest to finish. Performance tests should be in a different test run and will take longer.
  • Avoid magic numbers. A magic number is a number literal that appears in source code, usually for not explicable reason. One solution for this is extracting out to a constant for better readability. Another solution is to parameterize the number and have the default be put in a constant, that way you also get configurability.
  • Organize your code and tests in such a way that people can find things easily.
  • 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 IDE config files in it, use .gitignore for this (e.g. VSCode’s workspace.code-workspace)
  • The source tree should not have dependencies in it, use .gitignore for this (e.g. node_modules should be ignored)
  • Avoid useless comments. Only write a comment in your code if you want to point out something non-obvious

Database Expectations

Don’t know what feedback to give to your teammate? These are the standards we’re aiming for.

  • 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. The 344_db_utils also provide arguments to pass a SQL string and separate arguments to bind variables.
  • 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.
  • Maximize use of SQL; don’t do all the work in python!
  • Don’t pollute production with test data. Test data is for your tests folder, and code that would be delivered to a web application is in your src folder. Put yourself in the shoes of someone trying to deploy your system. They don’t care about your tests, but they do care about “it working”. For example:
    • Schema building, e.g. CREATE statements, belongs in the src
    • API methods that query, e.g. get_user_profile(id) belong in src
    • API methods that make modifications, e.g. create_user(name) belong in src
    • Test data insertion, e.g. INSERT INTO users(name) VALUES ('Jon Doe') belong in tests
    • Test methods, e.g. test_jon_is_a_user(self) belong in tests
  • 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.
    • Minimize API calls in a single test. For example, use your test data for setup, rather than calling CRUD operations for test setup. That way when something fails you won’t get many failures and that will reduce your debug time.
    • Iterate on your test data. As you come up with new test case ideas, you should also be updating your test data set.
    • Unit tests should not need joins in them - unit test code is intended to be straightforward and obvious.
  • Avoid flaky tests. A flakey test is one that breaks a lot. There are many reasons a test can become flakey. For example, a unit test that just counts the rows in a table will always break whenever you add a new row; instead, test table access differently.
  • On the topic of unit tests being idempotent with databases
    • You will need to pay attention to the order in which your data comes back (databases don’t guarantee order unless you tell them to sort the data), you’ll need to properly clean out the database between tests when necessary.
    • Be careful with auto-incrementing primary keys and test data. Keys can vary from run to run if you are not careful. For our setup, we recommend specifying primary keys in the test data.
  • Our convention is to use SQL keywords in all caps and identifiers in snake_case. e.g. SELECT * FROM my_interesting_table
  • Don’t make future maintainer have to know Postgres defaults by heart. For example, ORDER BY email - is that ASC or DESC? Instead, ORDER BY email ASC is preferable.

RESTful Expectations

  • Your resources should be nouns, usually plural
  • Use the correct verbs for CRUD operations
  • Don’t put sensitive data in the URL
  • Use parameters in header or body as appropriate (not just URL or query string!)
  • Don’t violate client/ server boundary

Client Expectations

  • Separation of style and content, specifically
    • CSS classes should have semantic names, not style-based names
    • Styling should be primarily in CSS files
  • Clean, simple UIs
    • Follow the UI design basics
  • Handle errors cleanly!
  • When using frameworks (e.g. React; reactstrap), follow best practices for the framework design