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 exa

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