[stack_framer]

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]

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