Removing outdated or file history comments

[Mark Rotteveel]

What is the opinion on removing outdated comment and file history
comments when you touch files for other reasons (talking about the
Firebird repo)? Personally, I don't see the point of keeping commented
out code, or file history comments from early 2000.

Mark
--
Mark Rotteveel

[Dimitry Sibiryakov]

'Mark Rotteveel' via firebird-devel wrote 01.07.2025 10:34:
> Personally, I don't see the point of keeping commented out code, or file history
> comments from early 2000.

If the comment describes *why* code was removed - it must be kept, IMHO.
History comments are not better than file log.

--
WBR, SD.

[Mark Rotteveel]

On 01/07/2025 10:38, 'Dimitry Sibiryakov' via firebird-devel wrote:
> 'Mark Rotteveel' via firebird-devel wrote 01.07.2025 10:34:
>> Personally, I don't see the point of keeping commented out code, or
>> file history comments from early 2000.
>
>   If the comment describes *why* code was removed - it must be kept, IMHO.

Even if it is commented out *because* it was replaced?

For example, I see no point in retaining this comment (or these
comments) in jrd/constants.h:

```
// BLOb Subtype definitions

/* Subtypes < 0 are user defined
* Subtype 0 means "untyped"
* Subtypes > 0 are Firebird defined
*/

// BRS 29-Apr-2004
// replace those constants with public defined ones isc_blob_*
//
//const int BLOB_untyped = 0;
//
//const int BLOB_text = 1;
//const int BLOB_blr = 2;
//const int BLOB_acl = 3;
//const int BLOB_ranges = 4;
//const int BLOB_summary = 5;
//const int BLOB_format = 6;
//const int BLOB_tra = 7;
//const int BLOB_extfile = 8;
//const int BLOB_max_predefined_subtype = 9;
//
```

>   History comments are not better than file log.
>


--

Mark Rotteveel

[Dimitry Sibiryakov]

'Mark Rotteveel' via firebird-devel wrote 01.07.2025 10:40:
> Even if it is commented out *because* it was replaced?

This is the only way to quickly find out why new code is better than old one
and assert if the decision to replace it was right or wrong.

> For example, I see no point in retaining this comment (or these comments) in jrd/constants.h:

Declarations are not strictly speaking a code.

> /* Subtypes < 0  are user defined
>  * Subtype  0    means "untyped"
>  * Subtypes > 0  are Firebird defined
>  */

I would move this comment to where isc_blob_* constants are defined now and
remove the rest.

--
WBR, SD.

[Mark Rotteveel]

On 01/07/2025 10:48, 'Dimitry Sibiryakov' via firebird-devel wrote:
> 'Mark Rotteveel' via firebird-devel wrote 01.07.2025 10:40:
>> Even if it is commented out *because* it was replaced?
>
>   This is the only way to quickly find out why new code is better than
> old one and assert if the decision to replace it was right or wrong.

That argument makes zero sense to me. That is what Git history is for.
You don't drag around commented out code for the rest of days just
because you want to see what it did in the past.

Mark
--
Mark Rotteveel

[Dimitry Sibiryakov]

'Mark Rotteveel' via firebird-devel wrote 01.07.2025 10:50:
>>    This is the only way to quickly find out why new code is better than old
>> one and assert if the decision to replace it was right or wrong.
>
> That argument makes zero sense to me. That is what Git history is for. You don't
> drag around commented out code for the rest of days just because you want to see
> what it did in the past.

Ah, I thought that we are talking about comments in code, not commented out
code. Sorry if I was wrong.

--
WBR, SD.

[Mark Rotteveel]

OK; I love comments in code (assuming they are not entirely irrelevant
or terribly out of date).

Mark
--
Mark Rotteveel

[Mark Rotteveel]

To be clear, I'm talking about:

1) Blocks of commented out code (possibly years ago)
2) The "revision" comments in the file headers (a practice that - as far
as I can tell - was stopped around 2004)

Mark
--
Mark Rotteveel