Hey fellow developers,
It’s my understanding that we want to improve the quality of submitted code, and that we want to do clearer design and motivation for new features. Here is my proposal for a little addition to the Code Review wiki page. Let me know what you think of this propossal; if you like it, click the heart. If you don’t like it, please explain why, and preferrably include a concrete way in which the process description can be improved.
Before adding a new feature (even a small one), it needs to be designed. As a minimum, the patch description should include the following where appliccable:
- Description of the problem that should be solved.
- List of alternative solutions, and a motivation as to why these are undesirable.
- Description of the proposed solution, and a motivation as to why this is the best solution.
- Limitations of the proposed solution.
- Mock-up of the proposed user interface and a description of how users are going to interact with the new feature.
These ingredients don’t have to be full essays. A few well-written sentences can be very illuminating as well.
The order in which these are listed is also relevant, as it helps to guide the reader towards understanding what the patch is doing (although I think depending on the exact text, swapping 2. and 3. could be clearer). To give a counter-example, starting a patch description with “This drop-down menu allows the artist to…” can be confusing, as the reader doesn’t know anything about the underlying problem yet.