4 ms·
> And later we finally realized comments are not optional except they very much are. the place to explain your payload is in the API documentation, not alongsi
by s1mplicissimus 1y ago
> And later we finally realized comments are not optional
except they very much are. the place to explain your payload is in the API documentation, not alongside the payload. It's not code.
- nwellinghoff 1y agoWhat about json schema files? Hmmm
- rkomorn 1y agoThat kind of stops working when (for example) your "payload" is configuration in a file where comments may make sense, though. I'm more partial to YAML for readability, but I don't think JSON configs are an awful anti pattern.
- raincole 1y agoThe exact issue is that JSON's usage spread far beyond "payload." > It's not code. package.json has a field literally called 'scripts' where the values are shell one-liners.
- tedggh 1y agoThis is true, but it is also true that if someone who didn’t read the documentation or the latest version of it, changes a config parameter that brings down a critical system you are responsible for, your bosses or customers won’t care if it was in the documentation or not.
- slowmovintarget 1y agoConfused puppy look https://orgmode.org/worg/org-contrib/babel/ https://orgmode.org/worg/org-contrib/babel/
- illuminator83 1y agoWhen you are commenting your schema, that's true. Anything which is generated by machines doesn't need comments either. But when it's written by people? And the values? That belongs with the 'payload'.