Add docstrings to functions and comments to explain complex logic, especially when the purpose or reasoning isn’t immediately clear from the code itself. This includes documenting function parameters, explaining non-obvious conditions, and clarifying implementation decisions or workarounds.
Functions should have docstrings that explain their purpose and parameters:
(defn convert-index
"Converts a numeric index to different formats based on delta value.
Args:
idx - numeric index to convert
delta - format selector (0=numeric, 1=letters, else=roman)"
[idx delta]
(cond
(zero? delta) idx
(= delta 1) (some-> (util/convert-to-letters idx) util/safe-lower-case)
:else (util/convert-to-roman idx)))
Complex conditions and workarounds should be explained with comments:
;; hovering on page ref in page-preview does not show another page-preview
;; if {:preview? true} was passed to page-blocks-cp
(page-reference false page {:preview? true} nil)
;; Check if edit input exists to prevent navigation when not editing
(not (state/get-edit-input-id))
Configuration options should include clear explanations and usage examples, especially for potentially risky settings or complex features.
Enter the URL of a public GitHub repository