Uploaded image for project: 'Data Management'
  1. Data Management
  2. DM-1077

Audit TCT recommendations to ensure that all standards updates were installed into Standards documents.

    Details

    • Type: Story
    • Status: Done
    • Resolution: Done
    • Fix Version/s: None
    • Component/s: TCT
    • Labels:
    • Story Points:
      2
    • Team:
      SQuaRE

      Description

      Audit TCT recommendations to ensure that all standards updates were installed into Standards documents.

      It was found that the meeting recorded in: https://dev.lsstcorp.org/trac/wiki/Winter2012/CodingStandardsChanges failed to include two recommendations:

      • recommended: 3-30: I find the Error suffix to be usually more appropriate than Exception.
        • current: 3-30. Exception classes SHOULD be suffixed with Exception.
      • recommended but not specifically included: Namespaces in source files: we should use namespace blocks in source files, and prefer unqualified (or less-qualified) names within those blocks over global-namespace aliases.
        • Rule 3-6 is an amalgam of namespace rules which doesn't quite have the particulars desired. FYI: The actual vote was to: "Allow namespace blocks in source code (cc) files."

      To simplify the future audit, all other recommendations in that specific meeting were verified as installed into the standards.

        Attachments

          Activity

          Hide
          robyn Robyn Allsman [X] (Inactive) added a comment -

          The two rules specifically mentioned here were added to the Standards documentation.

          The full audit is still in progress.

          Show
          robyn Robyn Allsman [X] (Inactive) added a comment - The two rules specifically mentioned here were added to the Standards documentation. The full audit is still in progress.
          Hide
          robyn Robyn Allsman [X] (Inactive) added a comment -

          The full audit has been completed on DM-272 and is In Review.

          For this Issue's completion:
          Refer to: https://confluence.lsstcorp.org/pages/viewpage.action?pageId=16908685 to view the revised: 3-30 and 3-6. Beware, the numbers are not in strict numerical sequence! Use your browser search to find the desired Rule.

          Show
          robyn Robyn Allsman [X] (Inactive) added a comment - The full audit has been completed on DM-272 and is In Review. For this Issue's completion: Refer to: https://confluence.lsstcorp.org/pages/viewpage.action?pageId=16908685 to view the revised: 3-30 and 3-6. Beware, the numbers are not in strict numerical sequence! Use your browser search to find the desired Rule.
          Hide
          jbosch Jim Bosch added a comment -

          Some these comments may be out of the scope of this issue, but since I'm looking through all the standards anyway, I think it's useful to mention those that are just a matter of clarity, rather than opinion:

          • Missing '=' in example for 3-6, which I just fixed myself.
          • 3-7: I think the term "template types" is a poor one; the usual C++ term would be "template parameters" for what we're talking about here. I also think the sentence about "template instances" has no place here; one might confuse a "template" (aka "template class") with a template instantiation, but no one would confuse a template parameter with a template instantiation. I also think the comment about this making template names stand out doesn't make much sense, as we do allow other names (e.g. classes) to be CamelCase with first letter uppercase.
          • 3-9: This is a confusing conflation of two entirely different concepts: it seems to discourage all global variables, regardless of whether they're in a namespace, but only to discourage free functions when they aren't in namespace. If that reading is correct, I think both are sensible recommendations, but they need to be clarified, and probably split up. If the reading should be that all free functions are discouraged, that'd be a terrible rule we violate all over the place. If the reading should be that global variables are only discouraged when not in a namespace, that needs to be clarified (and IMO it could be bumped up to a complete prohibition).

          Everything else looks fine. I of course still have personal disagreements with some of these points, and there are several I know we're in flagrant violation of in many places, but this definitely isn't the right forum for that discussion.

          Show
          jbosch Jim Bosch added a comment - Some these comments may be out of the scope of this issue, but since I'm looking through all the standards anyway, I think it's useful to mention those that are just a matter of clarity, rather than opinion: Missing '=' in example for 3-6, which I just fixed myself. 3-7: I think the term "template types" is a poor one; the usual C++ term would be "template parameters" for what we're talking about here. I also think the sentence about "template instances" has no place here; one might confuse a "template" (aka "template class") with a template instantiation, but no one would confuse a template parameter with a template instantiation. I also think the comment about this making template names stand out doesn't make much sense, as we do allow other names (e.g. classes) to be CamelCase with first letter uppercase. 3-9: This is a confusing conflation of two entirely different concepts: it seems to discourage all global variables, regardless of whether they're in a namespace, but only to discourage free functions when they aren't in namespace. If that reading is correct, I think both are sensible recommendations, but they need to be clarified, and probably split up. If the reading should be that all free functions are discouraged, that'd be a terrible rule we violate all over the place. If the reading should be that global variables are only discouraged when not in a namespace, that needs to be clarified (and IMO it could be bumped up to a complete prohibition). 3-12: Ha! You'll never get Robert Lupton to conform to this. Everything else looks fine. I of course still have personal disagreements with some of these points, and there are several I know we're in flagrant violation of in many places, but this definitely isn't the right forum for that discussion.
          Hide
          robyn Robyn Allsman [X] (Inactive) added a comment -

          Thanks for your complete review of this section. I updated the 3-7 commentary as you suggested. I can't do anything about the 3-12 slackers. I will send the rewriting of 3-9 to SAT since this is a significant rewrite which needs SAT approval and then forwarding to the TCT: DM-1510 - C++ Standards Rule 3-9 needs rewrite

          Show
          robyn Robyn Allsman [X] (Inactive) added a comment - Thanks for your complete review of this section. I updated the 3-7 commentary as you suggested. I can't do anything about the 3-12 slackers. I will send the rewriting of 3-9 to SAT since this is a significant rewrite which needs SAT approval and then forwarding to the TCT: DM-1510 - C++ Standards Rule 3-9 needs rewrite

            People

            • Assignee:
              robyn Robyn Allsman [X] (Inactive)
              Reporter:
              robyn Robyn Allsman [X] (Inactive)
              Reviewers:
              Jim Bosch
              Watchers:
              Jim Bosch, Robyn Allsman [X] (Inactive)
            • Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Summary Panel