[doc RFA] Use of FIXME, TODO, etc. in new code is prohibited.

[doc RFA] Use of FIXME, TODO, etc. in new code is prohibited.

[Doug Evans]

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
 

Re: [doc RFA] Use of FIXME, TODO, etc. in new code is prohibited.

[Mark Kettenis]

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

Re: [doc RFA] Use of FIXME, TODO, etc. in new code is prohibited.

[Doug Evans]

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

Re: [doc RFA] Use of FIXME, TODO, etc. in new code is prohibited.

[Eli Zaretskii]

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

Re: [doc RFA] Use of FIXME, TODO, etc. in new code is prohibited.

[Stan Shebs]

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