how do you document your backends? about backendlore HOT 4 CLOSED

Hi Bion! Thanks for your interest!

I write API docs manually and don't generate them automatically. It takes a bit of discipline, but what I do is document the behavior of the endpoint in terms of inputs and outputs (usually JSON body & JSON reply). Here's an example: https://github.com/altocodenl/acpic#routes . This level of documentation has been very helpful for both design & debugging.

In terms of comments within the code, I try to avoid them as much as possible. For sufficiently stable software, my golden standard would be to perform annotated source code (at least on the server code), but that's now a distant dream. Here's an example of what I mean by annotated source: https://github.com/fpereiro/dale#source-code

I'm not sure I understand your question about a Makefile to run infrastructure as code; are you referring to doc generation or to a provisioning/deployment process? I'd be glad to clarify further, although I'm far from an expert if it entails the latter.

Cheers!

from backendlore.

Hi @prateekrastogi ! I have very limited experience with Python and none whatsoever with Rust, so I cannot say anything in either regard...

from backendlore.

@fpereiro Please clarify your opinions on fast-scan indentation issues with Python and optional semi-colons permeability with Rust, if it entails you as a backendlore geek. ;-)

from backendlore.

Hi @bionicles ! Hope I answered your original questions; if I haven't, or you have new ones, feel free to reopen the issue or create a new one. Thanks!

from backendlore.