Coding style and proper use of version management tool are usually not considered a big deal in academic environment. However, if you are to collaborate as a group on some code, it’s better to take these into consideration. Reading toxic code in the morning can easily drain all of my energy the whole day.
- Always have up-to-date document describing what you have done. Ideally there should be a
README describing high level concepts and APIs. In the code there should be docstrings and helpful tips here and there.
- Use comment for describing extra details, not for temporarily commenting out code. You have version control for recovering old code.
- Delete all the unnecessary files. Figuring out there’re 20 files in the repository and only 2 of them are actually used and all the others are legacy files is not a good experience. You have version control for recovering old files.
- Laying out the files in a structured way. For example, put images in the
/imgs folder instead of letting it floating everywhere
- If using git as version control tool, commit every time when you add a new feature or fix some bugs. Do not put everything in a commit. This makes debugging hard since it’s not easy to revert it.
- Write useful commit messages. For example, which parameter is changed and why
- Never use
git add --all or git add .. Put random generated files in .gitignore, such as .DS_Store or __pycache__
- Look at other’s commit and take some time studying what they are doing.
- Spend some time for how to write Markdown and how to use Git. It’s not hard, if you are not too busy
Q&A