Work at SourceForge, help us to make it a better place! We have an immediate need for a Support Technician in our San Francisco or Denver office.

Close

#327 Prune comments from TEI source

AMBER
closed-accepted
Lou Burnard
Other (7)
4
2012-09-15
2011-12-08
Martin Holmes
No

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.

Discussion

1 2 > >> (Page 1 of 2)
  • Lou Burnard
    Lou Burnard
    2011-12-08

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

     
  • Martin Holmes
    Martin Holmes
    2011-12-08

    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.

     
  • Lou Burnard
    Lou Burnard
    2011-12-09

    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.

     
  • Lou Burnard
    Lou Burnard
    2012-03-13

    • milestone: --> AMBER
    • assigned_to: nobody --> louburnard
     
  • Lou Burnard
    Lou Burnard
    2012-03-13

    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.

     
  • James Cummings
    James Cummings
    2012-04-13

    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.

     
  • Martin Holmes
    Martin Holmes
    2012-04-18

    • status: open --> open-accepted
     
  • Martin Holmes
    Martin Holmes
    2012-04-18

    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.

     
  • Lou Burnard
    Lou Burnard
    2012-06-17

    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.

     
  • Lou Burnard
    Lou Burnard
    2012-09-15

    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

     
1 2 > >> (Page 1 of 2)