In this third module, you will be introduced to maintaining proper documentation within your code and on GitHub. This is important in the lab and in any situation where you will be tasked with coding. The team leads will be reviewing code before it gets pushed, but it must be properly documented before this is done. The reason we want to emphasize the importance of this is so that other students, including yourself, can always go back and understand what your code does and why it does it.
Our team uses C++ and/or Python for our projects. If you are not familiar with these, some references on each will be provided below. We suggest that you follow a tutorial on either one to get more comfortable with coding using one of those languages.
Please read through the following articles and complete the assignment below.
This is a simple example of how the Readme file on your project should look. Diagrams and charts are highly encouraged to be included, as this will provide the reader a better understanding of what you are explaining.
The takeaway from this is that good documentation is an ongoing effort, and it's crucial to invest time and effort into maintaining and updating it as you progress. Well documented code can improve your productivity and effectiveness, and contribute to the long-term success of your projects.
Note: If you ever need help with documentation, please feel free to ask a team lead or faculty member.
1. Sign into your GitHub Account.
2. Go to your repository: <YourName>_Training_Modules
3. Create a new branch called: Module3
4. Edit your Readme file in the Module3 branch and format it using the following:
- Please use a 5 line gap after the previous assignment
- The first line: "<YourName> Module Three" using H1 (header one)
- The third line: "Answers:" using H2 (header two)
- The fifth line: Start an ordered List (1.)
5. Answer the following questions by typing your short answers into the ordered list you created:
- How do you add a single-line comment in Python?
- How do you add a single-line comment in C++?
- How do you add a multi-line comment in Python?
- How do you add a multi-line comment in C++?
6. Commit your changes by clicking the 'Commit changes...' button and set the commit message to "Task Three"
7. Open one of the files labeled 'Mod2_python.py' or 'Mod2_c.cpp' (One is a python file, the other is C++):
- Save the file in a safe space on your desktop/workspace.
- Review the file and add comments to the code that tells the reader what it does.
- Save the document as "Module3-Q7" and stage, commit, and push it to the Module3 branch in the repository.
8. Create a simple program in Python or C++ where you add the sum of two numbers and determine if the sum is odd or even.
- Name your file: Mod3_Q8
- Remember to use appropriate naming conventions for your functions and variables.
- Add comments to the code.
- Stage, commit, and push your file to the Module3 branch in your repository.
9. Go back to your Readme file, and add the documentation of your Mod3_Q8 file. (See example below)
10. Commit your changes by clicking the 'Commit changes...' button and set the commit message to "Completed Task Three"
11. Go back to the code tab once you've committed your changes, and click the green button labeled 'Compare & pull request'
12. Fill in the pull request:
- Title: Task three
- Comment: [ Please write a one-two sentence summary of what you did for this assignment ]
- Assignees: [ Choose the team lead member who is overseeing modules ]
Example for Question 9
You have now completed your third assignment! 🚀
Just as a reminder, please notify a team lead when you have completed this task and provide your GitHub username. The next one will then be made available to you.
Here you will find some additional information on Documentation and Commenting code. If you have any suggestions on what should be added, please let a team lead know!