How to Program Racket

Matthias Felleisen, Matthew Flatt, Robby Findler, Jay McCarthy

Since 1995 PLT has grown from a handful of “repository contributors” to three dozen and more. This growth implies a lot of learning on our side and the introduction of inconsistencies of programming styles. It is time to leverage the former and to start reducing the latter. Doing so will help us, the developers, and our users, who use the open source code in our repository as an implicit guide to Racket programming.

To manage the growth of PLT and to showcase good Racket coding, we need rules that govern the contributions to the code base. These rules should achieve some level of consistency across the different portions of the code base so that everyone who opens files should easily find his way around.

This document spells out the rules. They cover a range of topics, from basic work (commit) habits to small syntactic ideas like indentations and naming.

Many pieces of the code base don’t live up to the rules yet. Here is how we get started. When you start a new file, stick to the rules. If you need to edit a file, you will need to spend some time understanding its workings. If doing so takes quite a while due to inconsistencies with the rules, please take the time to fix (portions of) the file. After all, if the inconsistencies throw you off for that much time, others are likely to have the same problems. If you help fixing it, you reduce future maintenance time. Whoever touches the file next will be grateful to you. Do run the test suites, and do not change the behavior of the file.

Also, look over the commit messages. If you see problems with the code deltas, let the contributor know. If you see a bug fix without docs and tests, let the contributor know. Code should be viewed by more than one person because a second person is likely to catch logical mistakes, performance problems, and unintended effects.

Request This document isn’t complete and it isn’t perfect. Consider it a call for improvements and suggestions. If you have ideas, contact the first author via email. If your request gets ignored, appeal to all four authors.

Note The recommendations in this style guide may not jive with what you grew up with. (They conflict with some of the ideas that the primary author had about style.) But if you do write code that ends up in the Racket code base, please follow the recommendations here. If/when someone else works on your code, this person may “fix” your code if it isn’t in compliance with the style guide.