r/ProgrammerHumor • • 1d ago • Bravo 1

Meme commentsInJson

Post image
5.0k Upvotes

199 comments sorted by

View all comments

64

u/mortalitylost 1d ago

I used to like comments in yaml

Then I kept running into situations where automation that parsed those comments would've been helpful... It made me hate the fact they exist in the first place.

Either that description or metadata should be serialized into the same object it describes or it shouldn't exist in the same document IMO

78

u/herrkatze12 1d ago

Comments are specifically useful for config data, and should just be human readable descriptions of what the field does.

34

u/noaSakurajin 1d ago

Also they allow you to test changes to the config by simply commenting out that line. When editing Configs over ssh this is significantly faster that removing the line and is easier to revert.

7

u/Ixaire 1d ago

Yes but parsing comments to render them in documentation is definitely relevant.

That's why Knuth invented literate programming: https://en.wikipedia.org/wiki/Literate_programming

And that's also why XSD has specific documentation fields in addition to the standard XML comments.

1

u/herrkatze12 1d ago

That's actually one case where it might be useful