* [doc RFA] Use of FIXME, TODO, etc. in new code is prohibited.
@ 2010-11-02 16:37 Doug Evans
2010-11-02 17:04 ` Mark Kettenis
` (2 more replies)
0 siblings, 3 replies; 5+ messages in thread
From: Doug Evans @ 2010-11-02 16:37 UTC (permalink / raw)
To: gdb-patches
Ok to check in?
2010-11-02 Doug Evans <dje@google.com>
* gdbint.texinfo (Coding Standards): Use of FIXME, TODO, etc.
in new code is prohibited.
Index: gdbint.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v
retrieving revision 1.327
diff -u -p -r1.327 gdbint.texinfo
--- gdbint.texinfo 20 Oct 2010 22:53:36 -0000 1.327
+++ gdbint.texinfo 2 Nov 2010 16:34:03 -0000
@@ -5855,6 +5855,9 @@ than trying to fit them into the 20 char
line, since either the comment or the code will inevitably get longer
than will fit, and then somebody will have to move it anyhow.
+The use of @code{FIXME} and all similar comments in new code is prohibited.
+The rule is to not write code that requires them.
+
@subsection C Usage
@cindex C data types
@@ -5980,7 +5983,9 @@ They exist mainly for consistency with t
@itemize @bullet
@item
-Use @code{FIXME} instead of @code{TODO}.
+The use of @code{TODO} is prohibited, as is @code{FIXME} and
+all similar comments.
+The rule is to not write code that requires them.
@end itemize
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [doc RFA] Use of FIXME, TODO, etc. in new code is prohibited.
2010-11-02 16:37 [doc RFA] Use of FIXME, TODO, etc. in new code is prohibited Doug Evans
@ 2010-11-02 17:04 ` Mark Kettenis
2010-11-02 17:06 ` Doug Evans
2010-11-02 18:49 ` Eli Zaretskii
2010-11-03 0:04 ` Stan Shebs
2 siblings, 1 reply; 5+ messages in thread
From: Mark Kettenis @ 2010-11-02 17:04 UTC (permalink / raw)
To: dje; +Cc: gdb-patches
> Date: Tue, 2 Nov 2010 09:37:06 -0700 (PDT)
> From: dje@google.com (Doug Evans)
>
> Ok to check in?
I think this is absolutely silly. If you really require all code to
be perfect and 100% complete, you'll never make progress. It is much
better to make small incremental changes. And if the author of such a
change realizes some of its deficiencies and bothers to document them
with a FIXME or a TODO, I consider that to be a good thing.
> 2010-11-02 Doug Evans <dje@google.com>
>
> * gdbint.texinfo (Coding Standards): Use of FIXME, TODO, etc.
> in new code is prohibited.
>
> Index: gdbint.texinfo
> ===================================================================
> RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v
> retrieving revision 1.327
> diff -u -p -r1.327 gdbint.texinfo
> --- gdbint.texinfo 20 Oct 2010 22:53:36 -0000 1.327
> +++ gdbint.texinfo 2 Nov 2010 16:34:03 -0000
> @@ -5855,6 +5855,9 @@ than trying to fit them into the 20 char
> line, since either the comment or the code will inevitably get longer
> than will fit, and then somebody will have to move it anyhow.
>
> +The use of @code{FIXME} and all similar comments in new code is prohibited.
> +The rule is to not write code that requires them.
> +
> @subsection C Usage
>
> @cindex C data types
> @@ -5980,7 +5983,9 @@ They exist mainly for consistency with t
> @itemize @bullet
>
> @item
> -Use @code{FIXME} instead of @code{TODO}.
> +The use of @code{TODO} is prohibited, as is @code{FIXME} and
> +all similar comments.
> +The rule is to not write code that requires them.
>
> @end itemize
>
>
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [doc RFA] Use of FIXME, TODO, etc. in new code is prohibited.
2010-11-02 17:04 ` Mark Kettenis
@ 2010-11-02 17:06 ` Doug Evans
0 siblings, 0 replies; 5+ messages in thread
From: Doug Evans @ 2010-11-02 17:06 UTC (permalink / raw)
To: Mark Kettenis; +Cc: gdb-patches
On Tue, Nov 2, 2010 at 10:04 AM, Mark Kettenis <mark.kettenis@xs4all.nl> wrote:
>> Date: Tue, 2 Nov 2010 09:37:06 -0700 (PDT)
>> From: dje@google.com (Doug Evans)
>>
>> Ok to check in?
>
> I think this is absolutely silly. If you really require all code to
> be perfect and 100% complete, you'll never make progress. It is much
> better to make small incremental changes. And if the author of such a
> change realizes some of its deficiencies and bothers to document them
> with a FIXME or a TODO, I consider that to be a good thing.
fwiw, I agree.
But I want to document what the rule(/convention) *is*, and the text
as written is my current understanding of it.
>> 2010-11-02 Doug Evans <dje@google.com>
>>
>> * gdbint.texinfo (Coding Standards): Use of FIXME, TODO, etc.
>> in new code is prohibited.
>>
>> Index: gdbint.texinfo
>> ===================================================================
>> RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v
>> retrieving revision 1.327
>> diff -u -p -r1.327 gdbint.texinfo
>> --- gdbint.texinfo 20 Oct 2010 22:53:36 -0000 1.327
>> +++ gdbint.texinfo 2 Nov 2010 16:34:03 -0000
>> @@ -5855,6 +5855,9 @@ than trying to fit them into the 20 char
>> line, since either the comment or the code will inevitably get longer
>> than will fit, and then somebody will have to move it anyhow.
>>
>> +The use of @code{FIXME} and all similar comments in new code is prohibited.
>> +The rule is to not write code that requires them.
>> +
>> @subsection C Usage
>>
>> @cindex C data types
>> @@ -5980,7 +5983,9 @@ They exist mainly for consistency with t
>> @itemize @bullet
>>
>> @item
>> -Use @code{FIXME} instead of @code{TODO}.
>> +The use of @code{TODO} is prohibited, as is @code{FIXME} and
>> +all similar comments.
>> +The rule is to not write code that requires them.
>>
>> @end itemize
>>
>>
>
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [doc RFA] Use of FIXME, TODO, etc. in new code is prohibited.
2010-11-02 16:37 [doc RFA] Use of FIXME, TODO, etc. in new code is prohibited Doug Evans
2010-11-02 17:04 ` Mark Kettenis
@ 2010-11-02 18:49 ` Eli Zaretskii
2010-11-03 0:04 ` Stan Shebs
2 siblings, 0 replies; 5+ messages in thread
From: Eli Zaretskii @ 2010-11-02 18:49 UTC (permalink / raw)
To: Doug Evans; +Cc: gdb-patches
> Date: Tue, 2 Nov 2010 09:37:06 -0700 (PDT)
> From: dje@google.com (Doug Evans)
>
> Ok to check in?
Texinfo-wise, I'm happy.
As for the issue itself, I think this is too stringent. I think the
original intent is to frown on FIXMEs that are easy enough to fix, but
I don't see any need to disallow them when they say something like
"gotta redesign and reimplement this whole GDB thing..." or something
like that. IOW, comments that talk about major jobs should be
allowed.
Thanks.
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [doc RFA] Use of FIXME, TODO, etc. in new code is prohibited.
2010-11-02 16:37 [doc RFA] Use of FIXME, TODO, etc. in new code is prohibited Doug Evans
2010-11-02 17:04 ` Mark Kettenis
2010-11-02 18:49 ` Eli Zaretskii
@ 2010-11-03 0:04 ` Stan Shebs
2 siblings, 0 replies; 5+ messages in thread
From: Stan Shebs @ 2010-11-03 0:04 UTC (permalink / raw)
To: gdb-patches
On 11/2/10 9:37 AM, Doug Evans wrote:
>
> +The use of @code{FIXME} and all similar comments in new code is prohibited.
> +The rule is to not write code that requires them.
I think there are a couple flavors of FIXME notes that we need to
distinguish.
The first is an obvious but easily-fixed limitation; fixed-size buffer,
not checking a return result, and the like. It seems good for software
quality that we make people fix those kinds of problems at submission time.
The other kind of FIXME is an enhancement idea that comes to mind while
working on a patch, but that is out of scope. Maybe you notice that a
routine could be shared between GDB and GDBserver, or that an argument
to a target vector method is now redundant. We have a rule discouraging
multi-change patches, and a volunteer's time might be insufficient for a
separate followon patch. In such a case we should record the idea
*somewhere* - major design changes might be wiki fodder, but the body of
the code seems like the right place for lesser worthwhile changes. We
could just recommend adding the note in running text, but a special
marker helps it stand out.
Stan
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2010-11-03 0:04 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2010-11-02 16:37 [doc RFA] Use of FIXME, TODO, etc. in new code is prohibited Doug Evans
2010-11-02 17:04 ` Mark Kettenis
2010-11-02 17:06 ` Doug Evans
2010-11-02 18:49 ` Eli Zaretskii
2010-11-03 0:04 ` Stan Shebs
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).