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

Port code style guidelines to new DM Developer Guide

    XMLWordPrintable

Details

    Description

      Verbatim port of DM Coding style guidelines to Sphinx doc platform from Confluence.

      I’m unclear whether these pages should be included:

      Any temptation to amend and update the style guideline content will be avoided.

      Attachments

        Activity

          http://docs.lsst.codes/en/tickets-dm-4656/

          See 'Coding Guides' section, which has a port of the coding standards (C++ and Python) originally published in the Confluence DM Developer Guide.

          jsick Jonathan Sick added a comment - http://docs.lsst.codes/en/tickets-dm-4656/ See 'Coding Guides' section, which has a port of the coding standards (C++ and Python) originally published in the Confluence DM Developer Guide.
          ktl Kian-Tat Lim added a comment - - edited

          It's https://confluence.lsstcorp.org/pages/viewpage.action?pageId=20283856 for "using using".

          Please add those three policies (above the double horizontal line for the C++11/14 policy) to the C++ guide (although the templates page has a rather different tone of voice than the others).

          While not changing the existing content is admirable, I do worry about references to "the lead developer" in the introductory text. I'll have to think about what might be appropriate to replace it.

          Still looking at the rest, but good so far.

          ktl Kian-Tat Lim added a comment - - edited It's https://confluence.lsstcorp.org/pages/viewpage.action?pageId=20283856 for "using using". Please add those three policies (above the double horizontal line for the C++11/14 policy) to the C++ guide (although the templates page has a rather different tone of voice than the others). While not changing the existing content is admirable, I do worry about references to "the lead developer" in the introductory text. I'll have to think about what might be appropriate to replace it. Still looking at the rest, but good so far.
          ktl Kian-Tat Lim added a comment -

          Oh, I see that two of the three others are in there.

          ktl Kian-Tat Lim added a comment - Oh, I see that two of the three others are in there.

          My thinking is that corrections to the content, especially content that is under TCT’s purview, can happen once the content is migrated (and thus can benefit from the JIRA/GitHub review process). I’m migrating some complex content like this in advance, but on Jan 4, SQuaRE is planning a one-day sprint to finish the rest of the developer guide content migration.

          I’d advise that we eventually merge C+11/14 and ‘using’ appendices into the main C+ style guide text.

          You’re right that I missed the page on C++ templates. I’ll migrate that now. I’m thinking that it should be a separate page under the ‘Coding Guide’ section of the documentation since that content seems to be more a tutorial than prescriptive guidelines. I anticipate that there would be similar coding tutorials in that section.

          jsick Jonathan Sick added a comment - My thinking is that corrections to the content, especially content that is under TCT’s purview, can happen once the content is migrated (and thus can benefit from the JIRA/GitHub review process). I’m migrating some complex content like this in advance, but on Jan 4, SQuaRE is planning a one-day sprint to finish the rest of the developer guide content migration. I’d advise that we eventually merge C+ 11/14 and ‘using’ appendices into the main C + style guide text. You’re right that I missed the page on C++ templates. I’ll migrate that now. I’m thinking that it should be a separate page under the ‘Coding Guide’ section of the documentation since that content seems to be more a tutorial than prescriptive guidelines. I anticipate that there would be similar coding tutorials in that section.

          I’ve migrated the ‘Using C++ Templates’ guide to http://developer.lsst.io/en/tickets-dm-4656/coding/using_cpp_templates.html

          jsick Jonathan Sick added a comment - I’ve migrated the ‘Using C++ Templates’ guide to http://developer.lsst.io/en/tickets-dm-4656/coding/using_cpp_templates.html
          ktl Kian-Tat Lim added a comment -

          I've done some spot checks and things look good.

          One minor thing: the C++ standard has numbered rules for reference. New or deleted rules are not supposed to cause renumberings. (Occasionally I think a number for an obsolete rule may have been reused for a new one.) Using those numbers as the link anchors might be slightly better than what appears to be the current use of heading text.

          We need to come up with a way to encourage people to only cite tagged versions of the standards (and maybe policies), and especially to distinguish any draft or in-progress modifications from official versions.

          ktl Kian-Tat Lim added a comment - I've done some spot checks and things look good. One minor thing: the C++ standard has numbered rules for reference. New or deleted rules are not supposed to cause renumberings. (Occasionally I think a number for an obsolete rule may have been reused for a new one.) Using those numbers as the link anchors might be slightly better than what appears to be the current use of heading text. We need to come up with a way to encourage people to only cite tagged versions of the standards (and maybe policies), and especially to distinguish any draft or in-progress modifications from official versions.
          jsick Jonathan Sick added a comment - - edited

          Per the issue with anchor links: I do set the anchor links according to the numbers, e.g., https://raw.githubusercontent.com/lsst-sqre/dm_dev_guide/tickets/DM-4656/coding/cpp_style_guide.rst so that a person can refer to :ref:`link <style-guide-cpp-2-1>` from reST or url#style-guide-cpp-2-1 from the URL. However there’s an idiosyncrasy in Sphinx’s HTML builder in that these anchor links are applied to the div s surrounding the section, while Sphinx auto slugifies an anchor for the hN element that the is offered to the user as an anchor link. Once the new docs are launched my plan is to implement a custom HTML5 builder for Sphinx that cleans up the markup and solves issues like this.

          The second point on citation is well taken. I think the issue of in-progress modifications is handled by the branching policy; merging a change to the style guides onto master would be considered making them ‘official.’

          To your larger point of having people cite tagged versions of these policies, we can have a discussion about that. As it’s setup now, the Developer Guide is served by Read the Docs, so we can have tagged versions published alongside the latest version. But this also means that the developer guide is tagged in unison, not as individual pages.

          jsick Jonathan Sick added a comment - - edited Per the issue with anchor links: I do set the anchor links according to the numbers, e.g., https://raw.githubusercontent.com/lsst-sqre/dm_dev_guide/tickets/DM-4656/coding/cpp_style_guide.rst so that a person can refer to :ref:`link <style-guide-cpp-2-1>` from reST or url#style-guide-cpp-2-1 from the URL. However there’s an idiosyncrasy in Sphinx’s HTML builder in that these anchor links are applied to the div s surrounding the section, while Sphinx auto slugifies an anchor for the hN element that the is offered to the user as an anchor link. Once the new docs are launched my plan is to implement a custom HTML5 builder for Sphinx that cleans up the markup and solves issues like this. The second point on citation is well taken. I think the issue of in-progress modifications is handled by the branching policy; merging a change to the style guides onto master would be considered making them ‘official.’ To your larger point of having people cite tagged versions of these policies, we can have a discussion about that. As it’s setup now, the Developer Guide is served by Read the Docs, so we can have tagged versions published alongside the latest version. But this also means that the developer guide is tagged in unison, not as individual pages.

          People

            jsick Jonathan Sick
            jsick Jonathan Sick
            Kian-Tat Lim
            Jonathan Sick, Kian-Tat Lim
            Votes:
            0 Vote for this issue
            Watchers:
            2 Start watching this issue

            Dates

              Created:
              Updated:
              Resolved:

              Jenkins

                No builds found.