This repository is focused on providing the information and tools necessary to write high quality Python and well documented Kettle Jobs & Transformations.
To setup the tools in this repository, please refer to git/README.md
Contents:
- Main
- Comments
- Input Defense
- Loops
- Duplicate Code
- Idiomatic Alternatives
- Commit Messages
- Commented Source Code
The bullets outlined below are minimal suggestions of what to look for when embarking on code review. They are meant to be interpreted on a case-by-case basis specific to the code you are reviewing and should take in to account your best judgement.
def foo():
...
if __name__ == '__main__':
foo()Comments about why the developer did something unusual are the most critical comments to look for. Comments like; MySQLdb returns long, typecasting to int first helps the reader understand the developers decision. Additionally, to catch bugs during code review, it's important to know what the code is supposed to do. Thus, when reading, you can compare actuality and intent.
Read more about Comment styling.
There are two main things to look for:
- Confirm that input from the end user is scrubbed and encoded.
- Confirm that functions are defended from bad inputs that come from external sources.
# defense example
def foo(int_param):
if not isinstance(int_param, int):
try:
int_param = int(int_param)
except ValueError:
return False
return TrueLoops should be checked for length, appropriate exit criteria, and speed. Loops with many objects may be considerably slower than loops with very few local variables; faster alternatives should always be considered.
Things like incorrect indenting or incorrect boundary conditions for loop exit are usual errors and are bugs that should be caught early on.
Read more about Loop performance.
Look for code doing similar things; this is an opportunity for refactoring and/or removing duplication. Consider that code doing similar things needs more maintenance, so when an input type changes, multiple places will need to change as well.
Look for code that can be replaced with Python idioms. Sometimes these idioms are more performant and generally makes code more readable.
Clearly written commit messages let us go back and find the point where something was changed. It takes longer to find the source of a bug if messages are poorly written.
git commit -m "Project: debugged issue with foo(). Tests pass."If code is commented out, it should be deleted. Leaving commented code in-place decreases readability. Utilize source control to re-introduce code that was previously removed.