Skip to content

Commit

Permalink
Adjust emphasis
Browse files Browse the repository at this point in the history
  • Loading branch information
imply-cheddar committed Mar 13, 2023
1 parent 92c24f6 commit 65024a0
Showing 1 changed file with 1 addition and 1 deletion.
2 changes: 1 addition & 1 deletion dev/style-conventions.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ This consistency applies to both log *and* exception messages.
* Messages INFO level or above (this includes all Exceptions) cannot leak secrets or the content of data. When choosing what to interpolate, it is important to make sure that what is being added is not going to leak secrets or the contents of data. For example, a query with a malformed filter should provide an indication that the filter was malformed and which filter it is, but it cannot include the values being filtered for as that risks leaking data.
* It is not always clear that something will leak information when the message is created. This is a shared responsibility and accidents can happen. If anything is discovered to leak or a message is suspected of be able to leak things, it should be opportunistically fixed. It is valid to include such fixes in PRs that are unrelated to the log-line specifically as it is more important that the fixes happen than that we have perfect separation of PRs.
2. Interpolated values should always be encased in a `[]` 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).
* Note, the `[]` is ***not*** the equivalent of a quote, it is an indication of interpolation. It is not a replacement for quotes nor is it attempting to be something that fits the normal rules of the English language. An interpolation is an ***optional*** addition to a message that helps accelerate the identification of next steps.
* Note, the `[]` is an indication of interpolation. It is not a replacement for quotes nor is it attempting to be something that fits the normal rules of the English language and quotation. An interpolation is an ***optional*** addition to a message that helps accelerate the identification of next steps.
* This means that when intepolating an array-like structure, we will see double `[]`. That is okay and a similar thing can happen no matter what we use to indicate interpolation.
3. Messages should read like a sentence and follow sentence-like structure.
* A nice way to validate this is that even if you were to remove interpolations, the message should still be readable and understandable. When a message requires interpolations to be meaningful, that is indicative of the message not carrying enough context.
Expand Down

0 comments on commit 65024a0

Please sign in to comment.