Manage Source Code

Team members are responsible for tracking and recording their work. This section describes practices that you are expected to follow in managing source code.

Design documents

You are not expected to produce design documents or diagrams for your features; details related to a particular task should be logged in the corresponding Git issues.

The exception to this guidelines are an ER diagram and class diagram that are explicitly listed as required. See track project artifacts for details.

Code comments

When writing code, you should add strategic code comments to explain the purpose of your code (not “what it does”, but “why is it done this way”). This does not need to be exhaustive, but it’s a good practice for complex and/or critical code.

If you use any external code (or code produced by GenerativeAI) then you are required to add a code comment inline, indicating the source of the code.

Feature branches

For large features, you should be using Git feature branches so that your work is isolated from your teammates. This involves

• Creating a branch for a feature,
• Working on that feature until complete,
• Merging back to the main branch,
• Checking that all tests pass on main,
• Finally commiting your changes.

GitLab has a built-in workflow that automates the process of creating a branch. Clicking on the Create Merge Request button in an open issue will automate creating a feature branch and associating it to the issue.

Code commits

You are expected to regularly commit your code to git. It’s a good practice to write your code incrementally:

1. Write a unit test for the code you are going to write. This helps define your interfaces.
2. Write code to achieve what you wanted and which also makes your test pass.
3. Add more tests to cover a reasonable number of inputs.
4. Commit to git!
5. Iterate.

Your Git commit history should reflect the work that you did during the sprint, and a TA should easily be able to see what commit belongs to which issue. A good practice is to put your issue number in the commit message to make it easy to find later!