I recently hired into a data analytics team for a hospital, and we don’t have a style guide. Lots of frustration from folks working with legacy code…I thought putting together a style guide would help folks working with code they didn’t write, starting with requiring a header for SQL scripts first as low hanging fruit.

Or so I thought.

My counterpart over application development says that we shouldnt be documenting any metadata in-line, and he’d rather implement “docfx” if we want to improve code metadata and documentation. I’m terrified of half-implementing yet another application to further muddy the waters–i’m concerned it will become just one-more place to look while troubleshooting something.

Am I going crazy? I thought code headers were an industry standard, and in-line comments are regarded as practically necessary when working with a larger team…

  • glue_snorter@lemmy.sdfeu.org
    link
    fedilink
    arrow-up
    3
    arrow-down
    1
    ·
    edit-2
    1 year ago

    Ugh, a Magic String (I call it that whatever the type)

    FACILITY_MAX_PRESSURES = {
        "Durham": 1000,
        "Ipswich": 500,
        "Calne": 750,
    }
    
    max_pressure = list(sorted(
        FACILITY_MAX_PRESSURES.values()
    ))[-1]
    
    if water_pressure > max_pressure:
        blah
    

    Obviously it should really pull from facility management, but that’s a bunch of moving parts where a constant is how you’d prefer the code to work

    Tbh it starts to look better to just define a constant and comment it.

    • RustySharp@programming.dev
      link
      fedilink
      arrow-up
      4
      ·
      edit-2
      1 year ago

      Tbh it starts to look better to just define a constant and comment it.

      Well… if (waterPressure > MAX_PRESSURE_BEFORE_YOU_FLOOD_THE_WHOLE_TOWN_OF_IPSWICH_AND_CALNE) is pretty self-documenting. No comments needed.

      • drdnl@programming.dev
        link
        fedilink
        arrow-up
        3
        ·
        1 year ago

        Although a bit long, I do like this almost impossible to ignore example of self documenting code :)