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…

  • pelotron@midwest.social
    link
    fedilink
    English
    arrow-up
    1
    ·
    edit-2
    1 year ago

    Hmm, do I want to open some external site/program to see my documentation or have it already in the code in front of me?

    We use doxygen at my company and I think I’ve only ever opened it twice in 9 years.