No single letter variable names

While single letter variables are acceptable in some cases (indexes in an array for instance), their proliferation makes code extremely difficult to read. Using a single letter variable forces you to trace the code to its definition and make sure it wasn’t changed along the way.

Variable names should state what they represent, not how or why. Single letter names can not possible convey what they represent.

Be explicit rather than implicit

The first version implicitly states that there can be two modes of the crop layer. I had to put my deductive reasoning skills to work to figure it out. Making the details of the crop layer explicit in the code makes it clear what the function does and does not do. If you find yourself deep inside nested if-statements, ask yourself, “what conditions do I know about that the reader might not know?” By explicitly saying what is handled rather than what it is not handled, you will find code easier to understand.

“Functions should do one thing, and do one thing well” -Craig Lancaster -Me

My mentor, Craig, said this to me many many times and I think it cannot be repeated enough. If your function truly does one thing well, it should be possible to communicate what that one thing is in the function name.

Name your function in a way that conveys what it does without having to the read its contents.

The function name _compute_crop_layer_output_shape communicates the intent without hiding any surprises inside. If you have a difficult time succinctly describing the intent of a function, it’s probably time to split it up into two (or more) functions that each do one thing well.

AI Index: 2017 Annual Report, http://www.aiindex.org/2017-report.pdf

The data science community is exploding right now. The popularity of AI and ML software is growing exponentially. Machine learning models are breaking into normal products. As machine learning becomes more mainstream, strong communication is key. Communicating code effectively to other engineers is a great place to start and will help the community grow even quicker.

Readable code makes bugs easier to spot. Readable code makes it easier for others to get involved. Readable code lets us spend our precious time solving interesting problems.

The code we are writing is ultimately not for ourselves. It is used and improved by many other people to solve problems in new ways.

As the data science community grows and machine learning is used more to create fresh experiences, comprehensible code is necessary to increase the velocity of the community.