{"thread":{"id":"64980","subject":"[PATCH] CodingGuidelines: document NEEDSWORK comments","startedAt":"2026-02-11T19:17:09Z","lastAt":"2026-02-14T15:36:25Z","messageCount":8,"participants":["Junio C Hamano","Patrick Steinhardt","D. Ben Knoble","Oswald Buddenhagen"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"535792","messageId":"xmqqms1ft7il.fsf@gitster.g","threadId":"64980","inReplyTo":null,"subject":"[PATCH] CodingGuidelines: document NEEDSWORK comments","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-02-11T19:17:06Z","receivedAt":"2026-02-11T19:17:09Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"We often say things like /* NEEDSWORK: further _do_ _this_ */ in\ncomments, but it is a short-hand to say \"We might later want to do\nthis. We might not. We do not have to decide it right now at this\nmoment in the commit this comment was added. If somebody is\ninclined to work in this area further, the first thing they need to\ndo is to figure out if it truly makes sense to do so, before blindly\ndoing it.\n\nThis seems to have never been documented. Do so now.\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/CodingGuidelines | 9 +++++++++\n 1 file changed, 9 insertions(+)\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex df72fe0177..b358d6bfb8 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -33,6 +33,15 @@ Git in general, a few rough rules are:\n achieve and why the changes were necessary (more on this in the\n accompanying SubmittingPatches document).\n \n+ - A label \"NEEDSWORK:\" followed by description of the things to be\n+ done is a way to leave in-code comments to document design\n+ decisions yet to be made. 80% of the work to resolve a NEEDSWORK\n+ comment is to decide if it makes sense to do so. It can be a very\n+ valid change to remove an existing NEEDSWORK comment without doing\n+ anything else, with the commit log message describing a good\n+ argument why it does not make sense to do the thing the NEEDSWORK\n+ comment mentioned.\n+\n Make your code readable and sensible, and don't try to be clever.\n \n As for more concrete guidelines, just imitate the existing code\n-- \n2.53.0-247-g50a2c88be3\n\n"},{"id":"535832","messageId":"aY1892Rzp1bQsLoW@pks.im","threadId":"64980","inReplyTo":"xmqqms1ft7il.fsf@gitster.g","subject":"Re: [PATCH] CodingGuidelines: document NEEDSWORK comments","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-02-12T07:10:47Z","receivedAt":"2026-02-12T07:10:53Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Wed, Feb 11, 2026 at 11:17:06AM -0800, Junio C Hamano wrote:\n> We often say things like /* NEEDSWORK: further _do_ _this_ */ in\n> comments, but it is a short-hand to say \"We might later want to do\n> this. We might not. We do not have to decide it right now at this\n> moment in the commit this comment was added. If somebody is\n> inclined to work in this area further, the first thing they need to\n> do is to figure out if it truly makes sense to do so, before blindly\n> doing it.\n> \n> This seems to have never been documented. Do so now.\n\nI noticed recently that there have been multiple patch series that\nblindly turn such NEEDSWORK comments into code. But I agree with you,\nthe first and most important thing that such an author would need to\nworry about is whether the comment still applies, and what the\nramifications of it are.\n\nI almost feel as if NEEDSWORK is a bit of a misnomer, and that something\nlike NEEDSTHOUGHTS would be a much better fit. But I don't have any\nintent to change that throughout our code base right now.\n\n> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\n> index df72fe0177..b358d6bfb8 100644\n> --- a/Documentation/CodingGuidelines\n> +++ b/Documentation/CodingGuidelines\n> @@ -33,6 +33,15 @@ Git in general, a few rough rules are:\n> achieve and why the changes were necessary (more on this in the\n> accompanying SubmittingPatches document).\n> \n> + - A label \"NEEDSWORK:\" followed by description of the things to be\n> + done is a way to leave in-code comments to document design\n> + decisions yet to be made. 80% of the work to resolve a NEEDSWORK\n> + comment is to decide if it makes sense to do so. It can be a very\n> + valid change to remove an existing NEEDSWORK comment without doing\n> + anything else, with the commit log message describing a good\n> + argument why it does not make sense to do the thing the NEEDSWORK\n> + comment mentioned.\n\nDocumenting is a good first step, but I have to wonder whether such\nauthors would even discover this. But even if not, it means that we have\nan easy place to point to going forward.\n\nThanks!\n\nPatrick\n"},{"id":"535868","messageId":"xmqq7bsiq8k3.fsf@gitster.g","threadId":"64980","inReplyTo":"aY1892Rzp1bQsLoW@pks.im","subject":"Re: [PATCH] CodingGuidelines: document NEEDSWORK comments","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-02-12T15:35:08Z","receivedAt":"2026-02-12T15:35:11Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Patrick Steinhardt writes:\n\n> I almost feel as if NEEDSWORK is a bit of a misnomer, and that something\n> like NEEDSTHOUGHTS would be a much better fit. But I don't have any\n> intent to change that throughout our code base right now.\n\nI somewhat disagree with this, by the way. Thinking has to be the\nfirst step of working for anybody. It is not like somebody thinks\nthings through thoroughly and writes an instruction to do these in\ncomments, only to be implemented by somebody else who does not have\nto think.\n\n>> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\n>> index df72fe0177..b358d6bfb8 100644\n>> --- a/Documentation/CodingGuidelines\n>> +++ b/Documentation/CodingGuidelines\n>> @@ -33,6 +33,15 @@ Git in general, a few rough rules are:\n>> achieve and why the changes were necessary (more on this in the\n>> accompanying SubmittingPatches document).\n>> \n>> + - A label \"NEEDSWORK:\" followed by description of the things to be\n>> + done is a way to leave in-code comments to document design\n>> + decisions yet to be made. 80% of the work to resolve a NEEDSWORK\n>> + comment is to decide if it makes sense to do so. It can be a very\n>> + valid change to remove an existing NEEDSWORK comment without doing\n>> + anything else, with the commit log message describing a good\n>> + argument why it does not make sense to do the thing the NEEDSWORK\n>> + comment mentioned.\n\nI wonder if adding a \"still\" there, i.e.,\n\n ... decide if it still makes sense to do so.\n\nmakes our intent clearer.\n\n> Documenting is a good first step, but I have to wonder whether such\n> authors would even discover this. But even if not, it means that we have\n> an easy place to point to going forward.\n\nYup.\n\nThanks.\n"},{"id":"535887","messageId":"xmqqldgxmzbj.fsf@gitster.g","threadId":"64980","inReplyTo":"xmqqms1ft7il.fsf@gitster.g","subject":"[PATCH v2] CodingGuidelines: document NEEDSWORK comments","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-02-12T21:22:56Z","receivedAt":"2026-02-12T21:22:59Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"We often say things like /* NEEDSWORK: further _do_ _this_ */ in\ncomments, but it is a short-hand to say \"We might later want to do\nthis. We might not. We do not have to decide it right now at this\nmoment in the commit this comment was added. If somebody is\ninclined to work in this area further, the first thing they need to\ndo is to figure out if it truly makes sense to do so, before blindly\ndoing it.\n\nThis seems to have never been documented. Do so now.\n\nSigned-off-by: Junio C Hamano \n---\n * reworded with a bit more stress on the possibility that the\n rationale behind NEEDSWORK comment may have gotten stale.\n\n Documentation/CodingGuidelines | 10 ++++++++++\n 1 file changed, 10 insertions(+)\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex df72fe0177..318829d4e4 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -33,6 +33,16 @@ Git in general, a few rough rules are:\n achieve and why the changes were necessary (more on this in the\n accompanying SubmittingPatches document).\n \n+ - A label \"NEEDSWORK:\" followed by description of the things to be\n+ done is a way to leave in-code comments to document design\n+ decisions yet to be made. 80% of the work to resolve a NEEDSWORK\n+ comment is to decide if it still makes sense to do so, since the\n+ situation around the codebase may have changed since the comment\n+ was written. It can be a very valid change to remove an existing\n+ NEEDSWORK comment without doing anything else, with the commit log\n+ message describing a good argument why it does not make sense to do\n+ the thing the NEEDSWORK comment mentioned.\n+\n Make your code readable and sensible, and don't try to be clever.\n \n As for more concrete guidelines, just imitate the existing code\n\nInterdiff against v1:\n diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\n index b358d6bfb8..318829d4e4 100644\n --- a/Documentation/CodingGuidelines\n +++ b/Documentation/CodingGuidelines\n @@ -36,11 +36,12 @@ Git in general, a few rough rules are:\n - A label \"NEEDSWORK:\" followed by description of the things to be\n done is a way to leave in-code comments to document design\n decisions yet to be made. 80% of the work to resolve a NEEDSWORK\n - comment is to decide if it makes sense to do so. It can be a very\n - valid change to remove an existing NEEDSWORK comment without doing\n - anything else, with the commit log message describing a good\n - argument why it does not make sense to do the thing the NEEDSWORK\n - comment mentioned.\n + comment is to decide if it still makes sense to do so, since the\n + situation around the codebase may have changed since the comment\n + was written. It can be a very valid change to remove an existing\n + NEEDSWORK comment without doing anything else, with the commit log\n + message describing a good argument why it does not make sense to do\n + the thing the NEEDSWORK comment mentioned.\n \n Make your code readable and sensible, and don't try to be clever.\n \n-- \n2.53.0-248-g282ed54c8f\n\n\n"},{"id":"535894","messageId":"CALnO6CAjd0vbi0S+giYBwsyQwFmSZoWUBQMKiUEokCEeaNTnrQ@mail.gmail.com","threadId":"64980","inReplyTo":"xmqqldgxmzbj.fsf@gitster.g","subject":"Re: [PATCH v2] CodingGuidelines: document NEEDSWORK comments","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2026-02-12T22:22:05Z","receivedAt":"2026-02-12T22:22:16Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"Small nit:\n\nOn Thu, Feb 12, 2026 at 4:23 PM Junio C Hamano wrote:\n>\n> We often say things like /* NEEDSWORK: further _do_ _this_ */ in\n> comments, but it is a short-hand to say \"We might later want to do\n> this. We might not. We do not have to decide it right now at this\n> moment in the commit this comment was added. If somebody is\n> inclined to work in this area further, the first thing they need to\n> do is to figure out if it truly makes sense to do so, before blindly\n> doing it.\n>\n> This seems to have never been documented. Do so now.\n>\n> Signed-off-by: Junio C Hamano \n\nThe opening quote '\"We might later…' doesn't appear to ever get closed.\n"},{"id":"535897","messageId":"xmqq3435mw18.fsf@gitster.g","threadId":"64980","inReplyTo":"CALnO6CAjd0vbi0S+giYBwsyQwFmSZoWUBQMKiUEokCEeaNTnrQ@mail.gmail.com","subject":"Re: [PATCH v2] CodingGuidelines: document NEEDSWORK comments","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-02-12T22:33:55Z","receivedAt":"2026-02-12T22:33:57Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"D. Ben Knoble\" writes:\n\n> Small nit:\n>\n> On Thu, Feb 12, 2026 at 4:23 PM Junio C Hamano wrote:\n>>\n>> We often say things like /* NEEDSWORK: further _do_ _this_ */ in\n>> comments, but it is a short-hand to say \"We might later want to do\n>> this. We might not. We do not have to decide it right now at this\n>> moment in the commit this comment was added. If somebody is\n>> inclined to work in this area further, the first thing they need to\n>> do is to figure out if it truly makes sense to do so, before blindly\n>> doing it.\n>>\n>> This seems to have never been documented. Do so now.\n>>\n>> Signed-off-by: Junio C Hamano \n>\n> The opening quote '\"We might later…' doesn't appear to ever get closed.\n\nYikes. Thanks for spotting.\n"},{"id":"536010","messageId":"aZBMQGQPiE3cJBUq@ugly.lan","threadId":"64980","inReplyTo":"xmqqldgxmzbj.fsf@gitster.g","subject":"Re: [PATCH v2] CodingGuidelines: document NEEDSWORK comments","fromName":"Oswald Buddenhagen","fromEmail":"oswald.buddenhagen@gmx.de","sentAt":"2026-02-14T10:19:44Z","receivedAt":"2026-02-14T10:19:46Z","isPatch":true,"sender":{"key":"oswald.buddenhagen@gmx.de","avatar":"https://avatars.githubusercontent.com/u/812380?v=4"},"body":"On Thu, Feb 12, 2026 at 01:22:56PM -0800, Junio C Hamano wrote:\n>+ - A label \"NEEDSWORK:\" followed by description of the things to be\n>\nby [a] description\n"},{"id":"536024","messageId":"xmqqms1bgww8.fsf@gitster.g","threadId":"64980","inReplyTo":"aZBMQGQPiE3cJBUq@ugly.lan","subject":"Re: [PATCH v2] CodingGuidelines: document NEEDSWORK comments","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-02-14T15:36:23Z","receivedAt":"2026-02-14T15:36:25Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Oswald Buddenhagen writes:\n\n> On Thu, Feb 12, 2026 at 01:22:56PM -0800, Junio C Hamano wrote:\n>>+ - A label \"NEEDSWORK:\" followed by description of the things to be\n>>\n> by [a] description\n\nThanks.\n"}]}