Hello people.
It seems that sometimes there are a few aspects of JME being worked on the repository, which makes a few classes not recommended for public adoption yet.
Also, I think we could benefit from a couple of policies for contributions like:
-
Obligation Strong recommendation of reviewing/adding Javadoc for every modified/added class. Including all methods and fields. If a method or field is inherited, it’s fine to reference the parent method. If the code is complex, it should be explained internally too (not only what it does, but how it does it).
- A few suggestions we could add:
3.1) If possible. Signal if the class is designed for inheritance, if it is known to be thread-safe or no thread-safe… and if it is stable (i.e. it is not known to need modifications). A simple paragraph for the class Javadoc will do it: "<p>This class has not been designed as thread-safe. Changes are expected to the constants, as they should be replaced for Enums.</p>"
3.2) Shall any implementation be fautly, add //TODO: or //FIXME: notes accordingly.
3.3) Reference examples, tests and related classes using @see Javadoc annotations and proper hyper-linked documentation.
My suggestion is that we start being very picky with undopcumented classes and commits. It may take only 10 minutes the first time, and the benefit will be huge. We shouldn't be afraid of adding as much documentation as possible to every class, cross-referencing related systems and going down to the basics as much as possible. Even including examples and/or references to the appropriate tests. We shouldn't accept commits without the corresponding Javadoc and internal documentation. We should validate all documentation for each commit.
I can imagine this will not always be possible to do, but in the end patches will follow the same process they follow now to be approved, with us just being more demanding about documentation.
I think there is a great benefit in being a bit more strict about this… and it's also considered a best practice.