Re: [PATCH] CodingGuidelines: document NEEDSWORK comments

Patrick Steinhardt [off-list ref] writes:

I almost feel as if NEEDSWORK is a bit of a misnomer, and that something
like NEEDSTHOUGHTS would be a much better fit. But I don't have any
intent to change that throughout our code base right now.

I somewhat disagree with this, by the way.  Thinking has to be the
first step of working for anybody.  It is not like somebody thinks
things through thoroughly and writes an instruction to do these in
comments, only to be implemented by somebody else who does not have
to think.

quoted

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index df72fe0177..b358d6bfb8 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines

@@ -33,6 +33,15 @@ 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 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 makes sense to do so.  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.

I wonder if adding a "still" there, i.e.,

    ... decide if it still makes sense to do so.

makes our intent clearer.

Documenting is a good first step, but I have to wonder whether such
authors would even discover this. But even if not, it means that we have
an easy place to point to going forward.

Yup.

Thanks.