This repository contains a selection of advice and examples of writing cleaner code. Entire books can, and have, been written on the subject (e.g. Clean Code by Robert Martin). These materials are primarily intended to help run workshops and lessons on writing cleaner code. They serve as a brief, but helpful, reference for some of the most common bits of advice.
This repo is also meant to facilitate better feedback among programmers. An editorial process like code review will help programmers write cleaner code. Engaging in code review exposes programmers to other styles and helps with better understanding likes and dislikes about different coding styles for finding your own.
While the focus of this content is on Python, there are fundmental similarities between it and R that are critical to understand for any programmer. These fundamentals will be covered as an exercise in identifying the utility of these comparable languages, and why or where one may be preferably used over another.
Although there is no explicit ordering to this content, when facilitating a workshop or working through these samples on your own, the following order is suggested:
- General Advice
- Giving and Receiving Feedback
- Examples *note that while these are in Python, they apply to both languages
- Helpful Tools and Resources For Clean Code and Review
The purpose of this repository is purely educational. The information and code here is provided without warranty. The text and code this repo has been released to the public domain with the exception of a piece of code copied from the Keras library found in examples/documentation-comments.py. That Keras code is licensed under the MIT license, which is included in the code file itself as well as the LICENSE file.
The rest of the code and text is in the public domain (the unlicense) and you may use it for any purpose, without restriction.
These materials were created by Tyler Bettilyon and Teb's Lab thanks to support from the The Scripps Research Institute, with additional contributions from TSRI's Sabah Ul-Hasan.
Support the creation of more free, open source, public domain educational materials by sharing them with others, subscribing to our newsletter, becoming a subscriber on Patreon, or arranging a training from Teb's Lab.
You can additionally support the creation and maintenance of our free materials by using them -- View the entire catalogue of free materials on the Teb's Lab website.