docs/coding-guidelines: Add document

[mxinden]

Description

Add document outlining a set of coding guidelines followed and to be followed across the rust-libp2p code base.

My goal is not to impose these guidelines onto anyone, nor to be dogmatic about them. Instead I would like to discuss their value, eventually establishing a shared mindset, helping newcomers getting started faster.

For now, this is a draft only. Lots of the wording still need polishing. Suggestions / feedback / disagreement is welcome anytime.

Links to any relevant issues

This might be a helpful resource for discussions like https://github.com/libp2p/rust-libp2p/pull/2622#discussion_r929649318 in the future.

Open Questions

Change checklist

• [ ] I have performed a self-review of my own code
• [ ] I have made corresponding changes to the documentation
• [ ] I have added tests that prove my fix is effective or that my feature works
• [ ] A changelog entry has been made in the appropriate crates

[thomaseizinger]

This blogpost might also go onto a further reading list: https://sans-io.readthedocs.io/how-to-sans-io.html

[mxinden]

This blogpost might also go onto a further reading list: https://sans-io.readthedocs.io/how-to-sans-io.html

I am a great fan of this coding style. It makes testing so easy.

That said, I don't think we apply this coding style anywhere within the rust-libp2p code-base. E.g. a Transport like libp2p-dns wrapps an I/O source, multistream-select wraps an I/O source, a ConnectionHandler has direct access to an I/O source. Thus I am having difficulties relating it to these coding guidelines.

[thomaseizinger]

This blogpost might also go onto a further reading list: sans-io.readthedocs.io/how-to-sans-io.html

I am a great fan of this coding style. It makes testing so easy.

That said, I don't think we apply this coding style anywhere within the rust-libp2p code-base. E.g. a Transport like libp2p-dns wrapps an I/O source, multistream-select wraps an I/O source, a ConnectionHandler has direct access to an I/O source. Thus I am having difficulties relating it to these coding guidelines.

Well, it does apply to some degree. NetworkBehaviour is basically a sans-IO state machine right? Swarm is passing events between the network and the behaviour with the minor exception that Substream has a boxed muxer inside that directly connects to the IO source. But given that we don't follow it fully, it is maybe not the best blog post to reference.