GitHub Actions is my new favorite free programming tool [video] • Hacker News Board

Re: GitHub Actions is my new favorite free programming tool [video]

#131

Post by stevehawk » Sat, Dec 21, 2019, 5:44 PM UTC

TheFiend7 wrote: post #73

stevehawk wrote: post #70

Earlier quoted context omitted.

> Github documentation is a disaster. They leave out critical parts. They don't provide examples. Everything they write is terse, confusing, and incomplete. Agreed. A lot of times they seemed to use the ole "make a blog post about X and we'll call it documentation" strategy that a lot of others seem to be employing as well. The net result is useless documentation that is often outdated by the time a product is live.…

While I do agree with you, I've found often times a good ol blog post with an example connecting some dots can be very productive. But I do agree with you that it's very from from being an alternative, and instead should be used to supplement healthy documentation.

I agree with that. I know I have also grown particularly jaded because I've read so many useless blogs as everyone is trying to push out their own Medium articles so they can get that hot new FAANG job.

Re: GitHub Actions is my new favorite free programming tool [video]

#132

Post by aassddffasdf » Mon, Dec 23, 2019, 6:19 PM UTC

pc86 wrote: post #27

aassddffasdf wrote: post #23

Earlier quoted context omitted.

Umm, GraphQL is a reflective API-- use 'introspection': https://graphql.org/learn/introspection/

I don't think that's the point.

It's my point so what is your point?

Re: GitHub Actions is my new favorite free programming tool [video]

#133

Post by aassddffasdf » Mon, Dec 23, 2019, 6:20 PM UTC

munk-a wrote: post #76

aassddffasdf wrote: post #23

Earlier quoted context omitted.

Umm, GraphQL is a reflective API-- use 'introspection': https://graphql.org/learn/introspection/

This same sort of introspection and auto-discovery was an original tenant of REST that's mostly ignored these days and I'm happy for that - I've never seen this sort of thing work well because it assuming you're able to translate data points into unambiguous identifiers. So the company object has a name object, I might assume that's the name of the company, but what if it's the registration number of the company - do…

That all comes down to how well-designed the API is. Not all APIs are created equal but in the hands of a skilled designer, this functionality is priceless. Not only that but you can also look at the actual values to tease apart any meanings that seem ambiguous (but, once again, in the hands of a good designer those won't exist in the first place).

Re: GitHub Actions is my new favorite free programming tool [video]

#134

Post by munk-a » Mon, Dec 23, 2019, 7:45 PM UTC

aassddffasdf wrote: post #133

munk-a wrote: post #76

Earlier quoted context omitted.

This same sort of introspection and auto-discovery was an original tenant of REST that's mostly ignored these days and I'm happy for that - I've never seen this sort of thing work well because it assuming you're able to translate data points into unambiguous identifiers. So the company object has a name object, I might assume that's the name of the company, but what if it's the registration number of the company - do…

That all comes down to how well-designed the API is. Not all APIs are created equal but in the hands of a skilled designer, this functionality is priceless. Not only that but you can also look at the actual values to tease apart any meanings that seem ambiguous (but, once again, in the hands of a good designer those won't exist in the first place).

I've seen a lot of "self-documenting" code in my time and it can be quite legible when starting in an organization that has good discipline... The issue is that there are always some weird edge cases and poorly named things that exist because "legacy" - in those cases a quick question should clear everything up, if you have access to someone in the know.

When it comes to APIs if you're eschewing documentation it's because (I hope) you are trying to minimize support costs and thus devs using the API won't have someone to ask questions of so those edge cases become mysterious and assumptions are made that may be wrong.

If you're designing an API that serves up items that may be on sale how would you name fields so that the price and possibly sale discount are unambiguous to read?