48
No more code headers? (midwest.social)
submitted 3 years ago by to c/programming@programming.dev
25 comments fedilink hide all child comments
 

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

you are viewing a single comment's thread
view the rest of the comments
[–] 2 points 3 years ago* (last edited 3 years ago) (1 child)

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.

  • permalink
  • fedilink
  • source
  • parent
  • hideshow 2 child comments
    •
  • [–] 4 points 3 years ago* (1 child)

    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.

  • permalink
  • fedilink
  • source
  • parent
  • hideshow 2 child comments
    •