Prune comments from TEI source

[TEITechnicalCouncil]

The TEI source XML is full of blocks of text which have been commented out at various times by editors, usually when they were superceded by another formulation of the same text, or have become obsolete. These unwanted blocks of code serve no purpose, since in Subversion we can retrieve any previous version of a document easily, and their presence makes it difficult to search the source code when you're bug-hunting or something like that.

I'd like to propose a purge of useless comments. Any comments not actually providing useful information for someone reading the source code should be removed, and in particular, all commented-out obsolete code should be removed.

Original comment by: @martindholmes

[TEITechnicalCouncil]

This issue was originally assigned to SF user: louburnard Current user is: lb42

[TEITechnicalCouncil]

I find the blank lines a lot more annoying than the comments persoally. It's true that we can always recover old versions from svn, but that implies we know there is a comment there to be recovered. I also find comments useful when a piece of code is bedding in, to explain why something has changed, or what it used to be. As you imply they do sometimes provide "useful information".

Original comment by: @lb42

[TEITechnicalCouncil]

I did say a purge of "useless comments". If you look at the end of USE.xml, for instance, you'll find a huge wodge of commented-out text, with no explanation as to why it's there or when it was commented out, or even if it was ever uncommented. It's just confusing to stumble over this stuff all the time. I'm all in favour of useful comments, though; I try to add them when I'm doing something that warrants it.

I have also been guilty of commenting out code I'm replacing instead of just deleting it, usually due to lack of confidence in what I'm doing. I think lots of people do that on the grounds that they'll come back later and remove the old code when they're sure the change is OK, but then they don't.

Why are blank lines annoying? I haven't noticed that many sequences of blank lines.

Original comment by: @martindholmes

[TEITechnicalCouncil]

I dont think we're in disagreement, except perhaps about what's useful. The case you mention -- at the start of the long wodge of comment at the end of USE, it does say that this is material which has been cut from elsewhere and moved here in case cutting it was a mistake. We did a fairly major reorganization at the time that the USE chapter came into being, with a lot of old DTD-specific material being removed, and it seemed wise to be cautious., But since the sky has not apparently fallen since then, I think we could probably remove all this now.

Original comment by: @lb42

[TEITechnicalCouncil]

I've now (rev 10154) purged the "material excised from elsewhere" collected at the end of USE. We should probably have a discussion about whether we want to systematically hunt down and kill other comments in the source, or whether there are other comparably massive bits of redundant guff we could now remove.

Original comment by: @lb42

[TEITechnicalCouncil]

• milestone: --> AMBER
• assigned_to: nobody --> louburnard

Original comment by: @lb42

[TEITechnicalCouncil]

As part of this, I noticed some time ago that p5subset.xml preserves comments making it larger than it needs to be. p5subset.xml should be condensed and partly minified (to the degree that it is still human readable but flattened).

While really a separate feature request, but maybe something we can just do, I mention it here for consistency in comment handling.

Original comment by: @jamescummings

[TEITechnicalCouncil]

This was discussed in Ann Arbor 2012-04, and LB was tasked with coming up with detailed instructions for how to deal with the variety of different types of comments that exist.

Original comment by: @martindholmes

[TEITechnicalCouncil]

• status: open --> open-accepted

Original comment by: @martindholmes

[TEITechnicalCouncil]

I think that comments appear in the source mostly for the following reasons: -- a change has been made which involves removing some stuff, typically a declaration or reference to one, but which has not yet been thoroughly tested enough for the commenter to be sure they might not want to revert it -- to draw attention to something unexpected such as something which looks strange, or a change which should be made but currently cannot be -- where stuff is considered redundant but not quite redundant enough to be definively removed, i.e. it might come back -- (very occasionally) to make a little joke

If comments were always dated and initialled it would be a lot easier to tell whether or not they were now redundant. I intend to date and initial all mine henceforth, and will also remove any that I know now to be past their sell-by.

I think the best recommendation for the moment is to let sleeping dogs lie. It just happens too often that a seemingly redundant comment actually helps explain a problem, or alerts us to something that might become one. For example -- the recent change in datatype of @n was a lot simpler to make because a comment alerted sebastian to a potential problem in DTD generation with the obvious solution.

Original comment by: @lb42

[TEITechnicalCouncil]

I am closing this since no specific action seems needed, beyond the general one of removing obviously redundant comments as and when we find them

Original comment by: @lb42

[TEITechnicalCouncil]

• status: open-accepted --> closed-accepted

Original comment by: @lb42