Forward.
---------- Forwarded message ----------
From: Caleb Williams <***@gmail.com>
Date: Mon, Mar 30, 2015 at 5:52 PM
Subject: Re: [Freecol-developers] First Successful Merge Request completed
To: "Michael T. Pope" <***@computer.org>
On Mon, Mar 30, 2015 at 5:29 PM, Michael T. Pope <***@computer.org> wrote:
> On Mon, 30 Mar 2015 14:11:20 -0500
> Caleb Williams <***@gmail.com> wrote:
> > On Mon, Mar 30, 2015 at 3:06 AM, Michael T. Pope <***@computer.org>
> wrote:
> >
> > > On Mon, 30 Mar 2015 01:13:32 -0500
> > > Caleb Williams <***@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.
>
No change. I cannot seem to access the discussion for the Merge Request
after submission.
> > 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.
>
Perfect. I understand that what I'm doing won't make a huge difference to
the end user, but hopefully can improve some things for the programmers.
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.
>
> I do try to do so, but unfortunately quite a bit of the code is over my
head. Now that I've changed the NetBeans code hint settings, I don't seen
Java Doc related hints at this time, so I'll have to leave that for another
time (when I know more about it) or for the next person to come along.
> 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.
>
If I could figure out how to do it, I could write some thing up. My issue
is getting past the fact that I'm not used to working on a command line
interface to such a degree that I almost need a GUI to get me through. Git
just seems to not work the way I want it to. I want it to be an interface
where I can see what I've submitted and remove any extraneous bits *before*
I submit the request, then once it's submitted, all the admin would see is
the proper merge request that will edit the existing FreeCol code.
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.
>
The other thing I'm not happy with is that Source Forge doesn't keep up
with changes automatically to the main tree. I'd like to be more automatic
in the way it clones out of FreeCol and into my own private repository.
Best,
--
*Caleb R. Williams*