3 ms·

I think we overlook wordiness too often! In fact, each "good" example in TFA can be shortened without losing context: Good: "I checked the foobar.py script an

I think we overlook wordiness too often! In fact, each "good" example in TFA can be shortened without losing context: Good: "I checked the foobar.py script and told Sarah that there was a bug related to updating the users table in SQL — the script does not seem to update the last name column." Better: "I found a bug in foobar.py and told Sarah it's not updating the last name column in the users table." Good: "Hi team, the email sending worker keeps crashing with the following exception. I've tried re-running, clearing the cache, re-installing dependencies. Can I get a hand?" Better: "The email sending worker keeps crashing with the exception below. I reran it, cleared the cache, and reinstalled dependencies. Can I get a hand?" Good: "The resource defines two routes, but the GET handler can only handle one of those — the one without any path params. I can technically make a request GET /api/foobar/123/456 and have the app crash with a 500 because there is a route but the handler doesn't take any params. Roughly speaking, there are two "types" of resource endpoints — list and singular. List type resource endpoints handle - getting a list of resources: GET /things - creating a new resource: POST /things Singular type resource endpoints handle - getting a single resource: GET /things/123 - updating a single resource: PATCH /things/123 - deleting a single resource: DELETE /things/123 To handle all cases properly, you need two resources: ... " Better: "The resource defines two routes but the GET handler can't take path params, so a request to GET /api/foobar/123/456 crashes the app with a 500. There are two "types" of resource endpoints: List: - get a list of resources: GET /things - create a resource: POST /things Singular: - get one resource: GET /things/123 - update one resource: PATCH /things/123 - delete one resource: DELETE /things/123 So you need two resources: ... "

pnt12 4y ago
You can have both of best worlds using BLUF: bottom line up front. I didn't read the code because it's too early to debug someone else's code, but here's an example: These endpoints break REST conventions and will be harder to understand and maintain. The convention is that GET /resources will list them, and POST /resources will create anew one. You can also use a path parameter to identify a resource you want to find with GET /resources/<id> or delete with DELETE /resources/<id>. I find it useful for two reasons: - maybe you parse the first paragraph and you have enough context to act, so you skip the second - or you parse the first paragraph and form the big picture in your mind, and that will make it easier to dive into the details

pnt12 4y ago

You can have both of best worlds using BLUF: bottom line up front. I didn't read the code because it's too early to debug someone else's code, but here's an example: These endpoints break REST conventions and will be harder to understand and maintain. The convention is that GET /resources will list them, and POST /resources will create anew one. You can also use a path parameter to identify a resource you want to find with GET /resources/<id> or delete with DELETE /resources/<id>. I find it useful for two reasons: - maybe you parse the first paragraph and you have enough context to act, so you skip the second - or you parse the first paragraph and form the big picture in your mind, and that will make it easier to dive into the details