Presto Development Guidelines

*** DRAFT -- THIS IS A WORK IN PROGRESS ***

Philosophy

• Presto is not a library. The exposed surface area is the SQL language, client protocol, JDBC driver, and SPI. The internals of Presto can and often do change drastically with release to release.
• SQL language features are forever. Anything added to the SQL interface should be considered permanent. For example, any newly added function is likely to be used by many users across thousands of stored queries. This means that removing a feature or changing the semantics is extremely difficult. While adding a new function may seem trivial, the naming and semantics, including all edge cases, must be considered carefully.
• Presto follows standard SQL (ISO/IEC 9075). If a proposed feature exists in the standard, we will follow the standard. If not, we carefully consider how to implement it without conflicting with a future version of the standard. When this is not clear, we often err on the side of not adding the feature.
• Correctness is of utmost importance. Users depend on Presto returning correct results.
• Stability and maintainability of the code over the long term is generally more important than adding features in the short term. While Presto is complex software and already has many features, we have much more work left to do. Keeping the architecture and code clean allows us to continue iterating and run the system successfully in production. Compromising this may allow us to move faster in the short term, but it will hurt us in the long term.
• Do things the simple way when possible. Only make it complicated when benchmarks or other data show that it is necessary. Complex does not mean unreadable. It is even more important to focus on readability and maintainability for complex code.

Required Reading

• Presto follows modern Java best practices as described in the excellent book Effective Java (EJ). Every developer should read this book. Note that when the book mentions "use X judiciously", that generally means do not use it in Presto. (Feel free to skip the section on Java serialization, as this is not used in Presto.)
• There are many things to consider when writing code that is readable and maintainable. Rather than attempting to list and explain all of them here with the rationale, we will defer to the book Clean Code.
• Many parts of Presto, especially in the execution engine, are highly concurrent. We strongly recommend reading Java Concurrency in Practice (JCIP).

Development

• As in accordance EJ and JCIP, favor immutable data structures where possible. In particular, use Guava immutable collections in preference to mutable collections.
• Use the utility classes in Guava, rather than Apache Commons (which we generally do not use in Presto). Many Guava utilities are now built into Java and should be used in preference to Guava.
• Avoid the log-and-throw anti-pattern. Exceptions can be handled by logging, or they can be re-thrown, but not both. Violating this rule results in the same error being logged multiple times in subtly different ways, which clutters the logs and makes troubleshooting harder.

Formatting

• Format code using the formatter rules.
• Parameter lists are often too long to be readable on a single line. When wrapping parameters, put each one on a separate line. Otherwise, keep them all on the same line. This applies to both declarations and call sites.
• Avoid abbreviations or acronyms in names, as these generally make code harder to read. For example, use executorService or simply executor rather than execSvc. There are a few exceptions to this, such as stats vs statistics.
• Common acronyms in names should should be capitalized as if they are words, rather writing them in uppercase. For example, write HttpClient or SqlParser, not HTTPClient or SQLParser. This improves readability, especially when multiple acronyms are used together. For example, consider HttpSqlDriver vs HTTPSQLDriver.