From aa94ba7d80c3b917a507f6975bd6400436fcd9e6 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Thu, 12 Feb 2026 13:22:56 -0800 Subject: [PATCH] CodingGuidelines: document NEEDSWORK comments We often say things like /* NEEDSWORK: further _do_ _this_ */ in comments, but it is a short-hand to say "We might later want to do this. We might not. We do not have to decide it right now at this moment in the commit this comment was added. If somebody is inclined to work in this area further, the first thing they need to do is to figure out if it truly makes sense to do so, before blindly doing it." This seems to have never been documented. Do so now. Signed-off-by: Junio C Hamano --- Documentation/CodingGuidelines | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index df72fe0177..d071f8e69f 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -33,6 +33,16 @@ Git in general, a few rough rules are: achieve and why the changes were necessary (more on this in the accompanying SubmittingPatches document). + - A label "NEEDSWORK:" followed by a description of the things to + be done is a way to leave in-code comments to document design + decisions yet to be made. 80% of the work to resolve a NEEDSWORK + comment is to decide if it still makes sense to do so, since the + situation around the codebase may have changed since the comment + was written. It can be a very valid change to remove an existing + NEEDSWORK comment without doing anything else, with the commit log + message describing a good argument why it does not make sense to do + the thing the NEEDSWORK comment mentioned. + Make your code readable and sensible, and don't try to be clever. As for more concrete guidelines, just imitate the existing code