-
Type: Improvement
-
Resolution: Unresolved
-
Priority: Trivial - P5
-
None
-
Affects Version/s: None
-
Component/s: None
-
Build
- Comments in yaml files should be valid syntax
- Comments in yaml files should be togglable by editors and yield valid syntax
(point #1 should be obvious, point #2 is described and discussed below)
Most editors have a default setting of adding/removing an extra space beyond the comment character when toggling a comment on a line (emacs does for me via comment-region/uncomment-region, VSCode also does this via editor.insertSpaceAfterComment for Toggle Line Comment Command+/, try toggling this in VSCode settings under Settings -> "Editor > Comments: Insert Space").
We have many yaml files in our source tree. Many of them have comment blocks that are intended to be easily uncommented. One poignant example is skipping the compile step in a sys-perf patch build.
We should standardize on ensuring the extra space exists between the comment character and the ensuing yaml syntax. This way, when engineers use the toggle comment feature in their editor, the produced code is correct.
I discovered this inconsistency when fixingSERVER-77769. In that case, inconsistent spacing between subsequent list members was very difficult to debug after uncommenting a block.
# - item_one # - item_two # - item_three # incorrect # - item_four
Linting comments and ensuring that they are valid when toggling the comment blocks would solve both the problems of inconsistent spacing for list members in addition to the correct number of spaces that editors toggle by default.
Proposed enforcement:
# - item_one # three spaces between comment character and yaml syntax # - item_two # - item_three # - item_four
When toggling a comment line or block with most editors yields this (correct syntax):
- item_one # two leading spaces - item_two - item_three - item_four
- is related to
-
SERVER-77769 SysPerf yml's compile-skip comment is incorrectly spaced
- Closed