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 s ( hat or?) into sonderful!h! ow!

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 checklist I use for the review of my code as well when I am on the other side as a . That 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 you need to do to create code in and to best position yourself in my .

Note: These” get ready for a useful code review” techniques are usually both 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 techniques are in addition to the previously discussed 21 coding techniques; I posted earlier. They are from my personal .

What is Photonai?

I share the seventeen techniques I use beforea of my changes to . There are code examples for some of these techniques. I also show how to personalize for some of these techniques for your projects.

already hascodethatreduces 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 , the motivation for your command selection in , or any other (ntegrated evelopment nvironment), 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 documentation on For example, I focus on a small subset of extensive command set that I use for .

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

pyCharm Version for this blog. Source: screen capture

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

Some of these animations may not appear in your app on your or device. have the same problem. If you forward this article to or , 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

Technique #1: Code Review Checklist

  1. Create a 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 when you accomplish a .

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 moment when you review code. As you advance as a programmer, you will find you are continuously updating your

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

Technique 2: Create Project

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

The animation showsadding the new project from a local directory in .

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 image (virtual environment) for your enterprise extensively in two other past articles. From these articles, we extract two techniques.

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

Illustration by Rachel Cottman

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

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

Technique #3: Create requirements.txt File

###### 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

Technique #4: Create a Virtual Environment

I show how to configure the virtual environment to use a (enhanced with J image.

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.

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 I participate in. Do not pass Go (literally). Immediately, the budding programmer is shown how to use and how they can successfully put their project under source code. The is rescheduled.

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

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

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 local history., and create a new branch at the end of work-day.

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

PyCharm Local file History feature, Animation by Rachel Cottman

Technique #6: Push your code to a shared repo.

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 or cloud-based repos.

Note: After the developer’s code passes their unit tests, they git push to the repo. The code is shared and can then be. 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.

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

Think of as

If code changes pass review, the designated attemptstomerge the changes. In case there are conflicts,

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

Choosing Styles for a Project

Technique #7: Choosing Documentation Style for a Project

There are many documentation styles for . , , and 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 . Don’t let this happen to you!

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

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

Technique #8: Use documentation template

You get a ! from me if you use the docstring template generatorwill 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_.

Insert the Numpy docstring template. Animation by Rachel Cottman

Technique #9 Put in Type Hints for every function and class method

Putting in type hints is relatively new. Only available since 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 ! 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.

is a dynamically typed language. I emphasize the word hints because type hints do not affect the . As far as you are concerned, the 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 = ''):

Technique #10: Use Python's Sphinx and Sphinx-apidoc tools

Ok, use of 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 and a review halt from me if they are not there.

Note: You will probably generate many errors and warnings from . 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

Technique #11: Choosing a Testing Framework

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 and a review halt from me if they are no (or not enough) unit tests.

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

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

Technique #12: All unit tests pass

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

Note: 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()

Technique #13: Unit test failure and exceptions

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 == ""

Technique #14: Unit tests cover entire signature

There should be an unit test for each argument. 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

Technique #15: Put shared project-level data structures for unit testing in a common file (optional)

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

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

Technique #16: Coverage report shows 70% or better

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 ! 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)

Individual unit test execution using

Pytest on a .py file. Animation by Rachel Cottman

Also, with you can run an entire test folder using

Pytest on a test folder. Animation by Rachel Cottman

Technique #17: Integration tests

The developer is not required to create integration tests. If they do, the developer risks getting one or more ! from me, depending on how many you created. However, you will get a 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

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

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

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

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

I write unit tests with 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 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).

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