On Mon, 30 Mar 2015 14:11:20 -0500 Caleb Williams <cale...@gmail.com> wrote: > On Mon, Mar 30, 2015 at 3:06 AM, Michael T. Pope <mp...@computer.org> wrote: > > > 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. > > > > I understand that better now. Thanks. The issue is that I cannot access the > Merge Request discussion in any way once it's been submitted. After that, > email is the only recourse.
This is a surprise. I have kicked your Sourceforge FreeCol permissions, hopefully improving your access. > That is the bulk of what I'm adding, which as I understand it hurts > nothing, but *can* help the compiler do its job. @Override is also a helpful reminder to the programmer. Its worth adding. However, please do not do this: + * @throws java.io.IOException This is just silencing a warning without adding anything for the programmer. The programmer can already see "throws IOException" in the function's signature. The same applies to "@param foo". I much prefer to see: @throws IOException <Simple reason why the exception is thrown> The quality of the explanation does not have to be high. What I hope for is for a human to have looked at it and thought about it, however briefly. Now, do you think you could write some documentation of the Merge Request system? doc/developer.tex would be the standard place for it. Just about everyone who uses it finds it confusing. While I am writing, just a warning that I am about to rework a bunch of the messages. If you have looked at FreeColMessages.properties, you can see that it is: 1. A mess 2. Has some naming conventions that are intermittently used I am going to add some new sections, enforce a naming convention for .../client.panel.*, and add a fair bit of comment. I have talked to the translatewiki people about how to minimize impact on them. Its likely to cause a lot of small changes all over the place, so beware if you have private trees. Cheers, Mike Pope
pgpT6nH8orWwP.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
