Seventeen Basic Techniques for a Code Review Checklist

It is code review time. Some of you would rather avoid the code review process. Whether you are new to programming or an experienced programmer, the code review is a shared learning experience for all involved. Rather than talk about “code review process best practices,” I share with you coding techniques I use to change code review from WTFs (What’s That For?) into WOWs (Wonderful! Oh! Wow!).

Image for post
Image for post
Wonderful! Oh! Wow! from Unsplash

My Approach to the Code Review Process

The anticipation of a code review process causes us to raise our game because we open-up our code for other programmers to see (criticize). It may look, feel, and bark like criticism. And just maybe it is. But like a bar fight, it is a chance for you to grow and bond with your team-mates. (seriously)

I have a Code Review checklist I use for the review of my code as well when I am on the other side as a Code Reviewer. That Code Review checklist is the basis for the techniques I share with you in this article.

Becoming a better programmer is a continuous process. The more code you write, the better you become. Good ways to become a better programmer are:

  1. Review at least two different codes and styles per week. Just skim the code for patterns, cute tricks, and new language features. Go deeper, if you see something that tugs at you.
  2. Join a company with experienced programmers that can mentor you. See #1 above.
  3. Collaborate with other coders on an open-source project; See #1 above.
  4. Experiment with new features and styles; See #1 above.
  5. Track the evolution of new releases of the language and supporting packages, libraries, and APIs.

I do not presume that I will make you a great programmer. (Though I sincerely hope you do.) Instead, I focus on coding techniques that I found over the years that helped me write better code and be a better code reviewer. (IMHO!)

In my examples, I focus on what you need to do to create code in Python and PyCharm to best position yourself in my code review checklist.

Note: These” get ready for a useful code review” techniques are usually both IDE and language independent. Most are techniques advice that can help you in any language.

I hope to show with this article that you can turn pain into gain. Instead, the code review is an opportunity to share new coding techniques or turn the table on the reviewers. I recommend the former course of action.

These Code Review Checklist techniques are in addition to the previously discussed 21 coding techniques; I posted earlier. They are from my personal Code Review Checklist.

What is Photonai?

I share the seventeen techniques I use before a code review of my changes to Photonai. There are Python code examples for some of these techniques. I also show how to personalize Pycharm for some of these techniques for your projects.

Photonai already has code that reduces manual coding and error by transforming supervised pre- and post-learner algorithms into elements with their argument signature. Examples of elements are several choices of data cleaners, scalers, imputers, class balancers, cross-validators, hyper-parameter tuners, and ensembles.

Why PyCharm?

The why, the motivation for your command selection in PyCharm, or any other IDE (Integrated Development Environment), is dependent on your preferences and familiarity and to a less degree approach, strategy, and tactics.

Note: In no way am I trying to replace JetBrain’s documentation on Pycharm. For example, I focus on a small subset of Pycharm’s extensive command set that I use for code review.

Note: I am using Pycharm 2020.1 Professional Edition on macOS. PyCharm rests on its virtual machine, to be platform-independent of hardware and operating system. It may be different on Windows or Linux. The free version will not have some of the features shown.

Image for post
Image for post
pyCharm Version for this blog. Source: screen capture

NOTE: All testing, documentation, and code checking tools can be used independently of (without) Pycharm.

Some of these animations may not appear in your Medium app on your iPhone or iPad device. Android may have the same problem. If you forward this article to Safari or Chrome, there is no problem. I suspect it has to do with the HTML5 <animate tag> and memory limitations. -author

Creating A Code Review Checklist for the Project

  1. Create a Code Review Checklist for this project;

Some of this checklist should be easy to put together. It should follow the outline of the coding standards document. Because it’s your checklist, you can focus on the thing that you struggle with and skip the things that you rarely, if ever, you have a problem. ref: smartbear.com

2. Review and update your Code Review Checklist when you accomplish a code review.

Code reviews are a chance to learn from both sides. Your checklist should include your strengths and weaknesses. Let yourself have the opportunity to learn and have a WoW moment when you review code. As you advance as a programmer, you will find you are continuously updating your Code Review Checklist.

# My code review checklist
- Create a Code Review Checklist
.
.
.

Creating a project is not part of the code review process. However, it is the first step in your project code lifecycle — the project in which you apply the Code Review Checklist.

The animation shows adding the new project Photonai from a local directory in PyCharm.

PyCharm Animation

Image for post
Image for post
Create a PyCharm Photonai project from a local directory. Animation by Rachel Cottman

Create A Reproducible Environment or Avoid Insidious Bugs (from) Packaging Error

I cover building a Docker image (virtual environment) for your enterprise extensively in two other past articles. From these articles, we extract two Code Review Checklist techniques.

First, I detail the directory structure template for any Python project and the Docker code. We found more flexibility using a Docker-Compose solution.

Image for post
Image for post
Illustration by Rachel Cottman

Also, I showed what the requirements.txt file plays a pivotal role.

Next, I showed how to put the Jupyter IDE and Jupyter extensions in a Docker image.

###### Requirements for project: Photonai ######numpy
matplotlib
progressbar2
Pillow
scikit-learn
keras
nilearn==0.5.0
pandas
nibabel
six
h5py
xlrd
plotly
imblearn
pymodm==0.4.1
scipy==1.2
statsmodels
flask
prettytable
seaborn
joblib
dask
distributed
scikit-optimize
scikit-image
pytest
photonai
pixiedust
pylint

I show how to configure the PyCharm virtual environment to use a Docker (enhanced with Jupyter) image.

PyCharm Animation

Image for post
Image for post
Configure a virtual environment (Docker) as the Python interpreter for PyCharm Rope project. Animation by Rachel Cottman

Version Control

Technique #5: Use version control on your local project file structure.

The absence of version control is one of two lacks that halts immediately any Code Review I participate in. Do not pass Go (literally). Immediately, the budding programmer is shown how to use Git and how they can successfully put their project under source code. The Code Review is rescheduled.

Note: I jump right into using the VCS git and GitHub/GitLab with little explanation. If you feel uncomfortable with the basic commands of GIT, please use references for GIT in the resources section of this article.

Everyone I know (including myself) use Git. In the past, I have used other VCSs (Version Control Systems), but for the last ten years, I have used Git.

One place I worked, stipulated a new local branch at least once per week while others, once per day.

I used to branch when test unit development started for a new file or class. I now use PyCharm’s local history., and create a new branch at the end of work-day.

PyCharm has a local history. Click-right in any file, and Pycharm pulls up file changes since the launch of Pycharm. local history is a very light VCS that has saved many developers.

PyCharm Animation

Image for post
Image for post
PyCharm Local file History feature, Animation by Rachel Cottman

Most organizations (public open-source project or private enterprise) have a Development and Production repository (repo). I observe that larger multi-project enterprises may have Alpha and Stage repos. Without exception, I push to GitHub or GitLab cloud-based repos.

Note: After the developer’s code passes their unit tests, they git push to the development repo. The code is shared and can then be Code Reviewed. If the code has bugs, the developer is notified of bugs and the test(s) that failed.

What is excellent, the developer, committer(s), and any other concerned party receive updates from GitHub/Gitlab actions.

What are the actions? Whew! A story for another time. Think of GitHub/Gitlab actions as callbacks. You can read about them at:

Think of GitHub/Gitlab actions as

If code changes pass review, the designated committer attempts to merge the changes. In case there are conflicts,

  1. the committer attempts to resolve;
  2. Any remaining conflicts are determined by a team consisting of the committer and the conflicted (sorry, could not resist) code authors.

Choosing Styles for a Project

There are many documentation styles for Python. Numpy, Google, and Pandas are some of the best-known styles. Your team has probably already standardized on one. Do not go cowboy and use a different style. I am sure you will be harshly criticized (and belittled) during your Code Review. Don’t let this happen to you!

PyCharm presents a list of five supported styles. The people I work with use the Numpy Style for docstrings because it is suited for detailed documentation of classes, methods, functions, and parameters.

PyCharm Animation

Image for post
Image for post
PyCharm set the docstring style to Numpy for the project Photonai 1.1.0., Animation by Rachel Cottman

You get a WOW! from me if you use the IDE’s docstring template generator. PyCharm will generate a docstring template with the keywords of your chosen docstring style as well as the method/function arguments as well as class attributes listed in the _self_.

PyCharm Animation

Image for post
Image for post
Insert the Numpy docstring template. Animation by Rachel Cottman

Putting in type hints is relatively new. Only available since Python 3.5 and higher version releases enable type hints (PEP 484). (two years ago?).

If you put in type hints, you can still earn a WOW! from me. Better hurry, I have a feeling that placement of type hints will become part of the baseline of required practices at your organization.

Python is a dynamically typed language. I emphasize the word hints because type hints do not affect the Python interpreter. As far as you are concerned, the Python interpreter ignores type-hints.

Note: The docstring no longer needs each arg and the return datatype to be documented. The signature becomes self-documenting.

Note: The readability as well as information of for type-checking tools has increased.

def __init__(self,
mongodb_connect_url: str = None,
save_output: bool = True,
plots: bool = True,
overwrite_results: bool = False,
project_folder: str = '',
user_id: str = '',
wizard_object_id: str = '',
wizard_project_name: str = ''):

Ok, use of Sphinx is not language independent, however most languages have a doc-tool. Use it on your code.

Similar to unit testing your code, you are testing your docstrings. It will leave HTML files around, which I will look for. You get a couple of WTFs, and a review halt from me if they are not there.

Note: You will probably generate many errors and warnings from Sphinx. You gain experience as you use Sphinx on which warnings to ignore. For example, Sphinx can complain when you use **kwargs.

Note: Please put docstrings for every class, method, or function. You can make it a one-liner. This will significantly benefit anybody that later reads your code. Notable examples of future readers are

  1. you;
  2. any code reviewers.

Unit Test Checklist

You will choose a test framework that is not language independent. However,most languages have a test framework. Use it on for your unit tests. You get a couple of WTFs and a review halt from me if they are no (or not enough) unit tests.

The PyCharm default test framework is Unittests. In the animation, I set the test framework to pytest.

PyCharm Animation

Image for post
Image for post
Setting the test framework to pytest in Pycharm for the project Photonai 1.1.0., Animation by Rachel Cottman

Make sure you run your unit tests, and they all pass before code review.

Note: pytest allows test classes and test functions.

# 1
def test_Hyperpipe_Data_XEqNone():
assert Hyperpipe.Data().X == None


# 2
def test_Hyperpipe_Data_Xarray():
test_value = np.ndarray((3,), buffer=np.array([0, 1, 2, 3]), dtype=int)
test_value = np.vstack([test_value, test_value])
assert (Hyperpipe.Data(X=test_value).X == test_value).all()

Put in unit tests for user error, especially bad signature invocation. If you raise exceptions, be sure to trigger them with unit tests.

#0
def test_Hyperpipe_pos_arg_erroe():
name = "myhype"
with pytest.raises(ValueError):
assert Hyperpipe(name).name == ""

There should be an unit test for each argument. PyCharm will generate a template for entire argument signature.

Type hints make it possible to accomplish bug hunting, finding security holes, and static type checking after the first pass of coding and unit testing.

# pyCharm generates signature unit test boilerplate for youclass test_Optimization:
def test_best_config_metric(self):
assert False

def test_best_config_metric(self):
assert False

def test_optimizer_input_str(self):
assert False

def test_optimizer_input_str(self):
assert False

def test_sanity_check_metrics(self):
assert False

def test_get_optimizer(self):
assert False

def test_get_optimum_config(self):
assert False

def test_get_optimum_config_outer_folds(self):
assert False

pytest.in shares functions and functions that return a data object when placed in the top test folder. You generate a WOW! from me if you have it. I should warn you; other reviewers give a WTF if you don’t have it.

@pytest.fixture()
def Housing():
dataset = fetch_california_housing()
return pd.DataFrame(dataset.data, columns=dataset.feature_names)

Run coverage before the code review. I expect as a baseline that unit tests all pass. If you show me a coverage report over 70%, you earn a WOW! from me.

However, if you show a coverage report over 85%, I discuss how you spend your time. Your time management may be OK; I just do not want you to go overboard. Especially since I think there soon will be a good test generation at the semantic level. (A great NLP project idea!) (again, IMHO)

Animation PyCharm: Individual unit test execution using pytest.

Image for post
Image for post
Pytest on a .py file. Animation by Rachel Cottman

Also, with PyCharm, you can run an entire test folder using pytest.

PyCharm Animation:

Image for post
Image for post
Pytest on a test folder. Animation by Rachel Cottman

The developer is not required to create integration tests. If they do, the developer risks getting one or more WOWS! from me, depending on how many you created. However, you will get a WTF if they don’t pass.

If the developer is senior and their assignment has a public API, I do expect an integration test or two. I won’t be surprised in the future if the integration test responsibility gets pushed over the wall to the developer. I have seen quite a few organizations doing this. It is quite common in the open-source community.

Resources

Summary

That is my first installment on items in my Code Review Checklist.

You can get a more updated Photonai code with all changes to-date from the public GitHub repo version. I recommend monthly updates, as Photonai is an on-going project.

Note: In case you can’t tell, I like PyCharm. I am not trying to sell you on using PyCharm. What I appreciate about PyCharm is that it almost fully-automates my development pipeline with a few mouse-clicks.

If you use PyCharm, then hopefully, some of the animations will help you with PyCharm setup and usage.

I try and document everything (emphasis on try) using PyCharm’s mouse-click inserted Numpy style template.

I write unit tests with pytest. PyCharm is generating much of the signature boilerplate for the class or function being unit tested. I run the unit test(s) individually, by file, or for the entire project.

I use the tool coverage to report on how much unit coverage on an individual class, method, function, or project.

In this article, you find my basic code review checklist. In my next article, I cover advanced code review techniques for checking code quality tools, performance increase techniques, security, and automated code review tools.

Remember, please share any of your techniques for a code review by leaving a comment or sending me email.. You may have an additional technique(s0) improvement on a given technique(s) or disagree with some of the techniques. Please send any coding techniques you would like to share. Please, also post your disagreement(s).

Written by

Physicist, Machine Learning Scientist and constantly improving Software Engineer. I extrapolate the future from emerging technologies.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store