This document attempts to describe the style that Druid code is expected to follow.
A large amount of the style conventions are handled through IDE configuration and automated checkstyle rules.
druid_intellij_formatting.xml
.eclipse_formatting.xml
.While this page might discuss conventions that are also enforced via said mechanisms, the primary intent is to discuss style-related convention that cannot be (or are extremely difficult to be) enforced through such automated mechanisms.
The way that log and exception messages get formatted is an important part of a project. Specifically, it is important that there is consistency in formatting such that someone can easily identify and interpret messages. This consistency applies to both log and exception messages.
[]
and come after a noun that describes what is being interpolated. This is to ensure that enough context on what is happening exists and to clearly demark that an interpolation has occurred. Additionally, this identifies the start and end of the interpolation, which is important because messages that attempt to mimic natural prose that also include interpolation can sometimes mask glaring problems (like the inclusion of a space).[]
is an indication of interpolation. Its closest cousin in terms of grammatical structures is the Apposition. Given that the interpolation specifies a specific instance of the noun, it would be considered “restrictive” and normal English rules would dictate that it come immediately in the sentence without any sort of punctuation. If we were to follow these rules, we would lose track of what is in the interpolation and what is not, so we encase in []
to help identify the start and end of the Apposition. As with appositions, the interpolation is an optional addition to our messages that helps accelerate the identification of next steps.[]
. That is okay and a similar thing can happen no matter what we use to indicate interpolation.log.info("%s %s cannot handle %s", "null", "is not null", "INTEGER")
"null is not null cannot handle INTEGER"
" cannot handle "
log.info("column [%s] filter [%s] cannot handle type [%s]", "null", "is not null", "INTEGER")
"column [null] filter [is not null] cannot handle type [INTEGER]"
"column filter cannot handle type"
log.info("Filter [%s] on column [%s] cannot be applied to type [%s]", "is not null", "null", "INTEGER")
"Filter [is not null] on column [null] cannot be applied to type [INTEGER]"
"Filter on column cannot be applied to type"
For the majority of style considerations, the Apache Druid documentation follows the Google Developer Documentation Style Guide. For more details, see Contribute to Druid docs.