On Mon, 30 Mar 2015 01:13:32 -0500 Caleb Williams <cale...@gmail.com> wrote: > Plus it didn't help that I misinterpreted Michael's comment on the > merge request.
I should probably clarify here (rather than on the merge request) some
JavaDoc practices used in FreeCol. Obviously there are two consumers of
JavaDoc: humans reading the code, and JavaDoc-manipulating programs. The
former is more important IMHO:-), but the latter can not be ignored.
- There has been little consistency about when JavaDoc is added. It is ok
to add new code without it, especially for small obvious routines. I
personally prefer to err on the side of more doco rather than less, but
I have never seen a contribution bounced due to its documentation or
lack thereof.
- Functions that inherit documentation just get {@inheritDoc} and nothing
more. Anything else is clutter. Of course, @Override etc is ok though.
- Running "ant javadoc" every so often, and cleaning up the inevitable
slips is a good idea.
Cheers,
Mike Pope
pgpIKqhbnOb9E.pgp
Description: OpenPGP digital signature
------------------------------------------------------------------------------ Dive into the World of Parallel Programming The Go Parallel Website, sponsored by Intel and developed in partnership with Slashdot Media, is your hub for all things parallel software development, from weekly thought leadership blogs to news, videos, case studies, tutorials and more. Take a look and join the conversation now. http://goparallel.sourceforge.net/
_______________________________________________ Freecol-developers mailing list Freecol-developers@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/freecol-developers
