How To Submit Code for Review (and Final Submission)
Goals
Most modules will require some programming, you will often have to submit this code as part of an assessment. Even if you don’t submit your code for an assessment, preparing code for review is necessary to help other people critique and troubleshoot your code. Finally your will you will also need to make your own notes as you learn. This means it is important that your code is readable: both to others and to you.
Remember that you will read code far more often than you will write it. So even for your own notes you need to be able to understand what your code is doing. Both now and in several months (or years) time when you come back to look at it.
This checklist summarises the minimum activities you should complete before a code review. You can also find guidance on tools and activities for specific languages in the sections below.
Submission Checklist
- File Headers. Do all files have an explanation of what the file is for? Is the appropriate license in place, if required?
- Structure Comments. Do all classes, enumerations, functions, etc. have a clear comment outlining the parameters, use of the structure, corner cases, and other notes on appropriate use?
- Code Comments. Are all algorithms and data-structures appropriately commented: ideally with references? Are corner cases, missing data, stub-code and other elements the reader needs to pay attention to noted?
- Code Formatting. Is the code formatted appropriately, ideally using a tool or standard guide? See below for language specific tasks
- Code Linting. Does the code meet guidelines for readability? Are the language elements chosen appropriate (for example, to check for depreciated usage)? See below for language specific tasks
- Test Cases. Are appropriate unit, functional and integration tests included?