Contribution guidelines

Reason: Below is a small extract from Google Code style guide that summarizes the reasoning quite well:

Optimize for the reader, not the writer Our codebase [...] is expected to continue for quite some time. As a result, more time will be spent reading most of our code than writing it. We explicitly choose to optimize for the experience of our average software engineer reading, maintaining, and debugging code in our codebase rather than ease when writing said code. "Leave a trace for the reader" is a particularly common sub-point of this principle: When something surprising or unusual is happening in a snippet of code[...], leaving textual hints for the reader at the point of use is valuable.

See: here

In particular, commenting on source code has been covered in many places, for example: here.

Steps: Come up with a convention and create a way-of-working document that contributors to the project adhere to. It doesn’t have to be a set-in-stone rulebook but rather some common guidelines. For example, the following has proven to be extremely helpful:

Pull Requests should always link to corresponding Github Issues. Preferably using keywords
No Empty description in Pull Requests
Always answer the “why” question for code changes. Agree on a reference for comment style.
No commenting out of code without obvious reasons.
Do not create “backup files”. We have Git in case we need to go back to a previous version of the code.

Definition of done: A way-of-working document exists in the repository that guides new and existing developers on how to contribute to this repository. Ideally in Github’s CONTRIBUTING.md file.

d-rec / drec-origin

Contribution guidelines #405