Creating a README.md file is extremely important to explain your project. The README should contain:
A title and short description explaining what the project is about. Keep it concise.
Table of contents to help navigation if it’s a large README.
Installation instructions on how to run/set up the project locally. Explain any software/tools needed.
How to use the project including example usage and explanations of important files/folders.
Project architecture/structure – overview of files/folders and what they contain.
Screenshots/recordings to demonstrate key functionality.
Known issues/bugs and planned future enhancements.
Documentation for APIs, classes, functions etc using markdown syntax.
Contributors/credits – thank people who helped with the project.
License information – include a license file and specify the type of license (e.g. MIT).
Use appropriate Git features to leverage the benefits of version control for your project:
Create separate branches for new features/bug fixes and merge into main once complete.
Commit changes frequently with descriptive, concise messages explaining what was changed.
Leverage GitHub issues for tracking bugs, enhancements, support questions. Cross-reference issues in commit messages.
Use pull requests for reviewing changes before merging into main branch. Discuss code in pull request conversations.
The project code structure should be well organized, consistent and documented:
Follow standard conventions for file/folder names, naming variables etc to aid readability.
Separate code into logical modules/packages by functionality using folders.
Write modular, reusable code with well-defined separation of concerns.
Include comments in code to explain intention/purpose, especially for complex logic.
Document public APIs, classes and functions using docblocks/comments.
Format code consistently following a recognized style guide (PEP8, Black etc).
Write automated tests to validate code works as expected and prevents regressions.
For accessibility and easier collaboration, consider including:
Detailed contributor guidelines for tasks beginners can help with to get involved.
CI/CD workflows to run tests and build/deploy automatically on new commits.
Info on how to report security issues discreetly using HackerOne/Bugcrowd.
A code of conduct with guidelines for respectful participation and discussions.
Requirements.txt or package.json file listing project dependencies and versions.
Common files/folders to exclude from source control using .gitignore.
Documentation on deploying/running in production-like environments.
Hosting the code publicly on GitHub also allows:
Reviewers to check coding standards, quality and give feedback to improve.
Potential employers can evaluate skills when applying for jobs.
Community contributions like bug fixes, enhancements or translations.
Automatically generated stats on GitHub like traffic, forks, stars as morale boost.
Long term preservation even after graduation through GitHub archives.
Proper documentation and organisation helps demonstrate skills, makes code more accessible and reusable. Open source practices implemented effectively can result in higher quality code and collaborative projects through community involvement. Regularly engaging with GitHub features is also helpful for career prospects. With some planning, GitHub is a great place to host capstone work publicly.
Andrew Stroud