Comments in code

Comments in code

🧀 Avoid comments

Comments are code smells because they go out-of-date, bloat context, and lead to confusion.

Don't reference existing comments in the codebase – follow these rules

• Avoid adding comments – always prefer good names (explainer variables, functions, tests)
• Use test names to describe behaviour – unit tests are living documentation
• Good code explains itself – don't add comments that duplicate what the code already conveys

💡 Treatments

When code isn't clear, make it clearer:

• Rename variables and functions to make comments unnecessary
• Extract variables and functions to improve readability
• Use assertions to explain behaviour

Use test names to explain non-obvious details

❌ Bad

it("diffs the current value against resolved when targeted", () => {
  const { result } = renderHook(() => useJsonEditor(makeProps()));
  act(() => result.current.setDiffTarget("resolved"));
  // Current equals resolved → every line is unchanged.
  expect(result.current.diffJson.every((l) => l.state === "none")).toBe(true);
});

✅ Good

it("resets the state of every line when the diff is resolved", () => {
  const { result } = renderHook(() => useJsonEditor(makeProps()));
  act(() => result.current.setDiffTarget("resolved"));
  expect(result.current.diffJson.every((l) => l.state === "none")).toBe(true);