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 <gitster@pobox.com>
This commit is contained in:
Junio C Hamano
2026-02-12 13:22:56 -08:00
parent 9a2fb147f2
commit aa94ba7d80

View File

@@ -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