[jsword-devel] monster check-in

[DM Smith]

I have a tendency to be a bit long winded, so don't take my thoughts as 
argumentative.

Joe Walker wrote:
> 
>  >> 2 parts I've not checked-in are i18n field names and i18n case
>  >> changes.
>  >> I'd like to have a quick debate about the first (separate mail -
>  >> probably tomorrow)
> 
> The question is 3 fold. Style, Scope and Positioning
> 
> Style: The resource names are LIKE_CONSTANTS because I wrote a couple of
> vi macros to do the work and only going that far made things easy. 
> However by including the class name in the lookup where resources are
> package scoped we have a mix of scopings. And on the scope front ...

I think that whatever style is adopted it should be applied 
consistently. Either all UPPERCASE with _ separating words or MixedCase, 
like class names. The former does convey the constant nature of the 
resource. The latter is in line with all the examples and Sun's 
recommendations.

It does not matter to me which is chosen, as long as it is consistent.

> 
> Scope: We have a growing number of resource files, some are class based
> (settings files, ActionFactory files) and some are package based (Msg
> resource files). For ease of translation, application based might be
> easier. For ease of maintenance class based would be easier.
> Which should we tend towards? My gut reaction is to have them class 
> based, we could easily write a tool to help with translation, but a tool 
> to help with maintenance is less obvious. But I'm not sure that this 
> goes as far as Msg files, if we split those up we would have zillions of 
> resource files rather than trillions. Which brings be to positioning ...

I think that as J-Sword approaches 1.0, the code is becoming stable. 
That is to say it is changing less and less. Splitting the Msg file from 
one per package to one per class would be tedious (as you have already 
found when you did it to the ActionFactory. Great job, by the way!)
But once done, it would not require much effort to maintain as it 
probably will not change much.

The problem with splitting it out is that some messages are used by more 
than one class. Would we copy these?

The approach that I have taken in the first go at the Msg files is to 
prefix each resource with a class that uses the resource (i.e. 
ClassName.ResourceKey). If a resource was used by more than one class I 
picked one class name to be the home for that resource. My methodology 
was somewhat arbitrary. I tried to think about inheritance and which 
class had the most resources.

The reason I scoped individual resources was to increase tracibility. I 
think that with a per package approach it is too easy for resources to 
become orphaned. In fact, I found that to already be happening. If a 
class is being refactored, deleted or moved, it is easier to glance at 
the Msg.properties file and see what resources need to be migrated. 
Otherwise, one would have to examine the class file for uses of Msg and 
analyze each of those uses.

Scoping also has another advantage, it provides an automatic mechanism 
for disambiguation. Specifically if two different classes have an ERROR 
msg and they need to have different content, one does not need to be 
clever in coming up a name. ClassA.ERROR and ClassB.ERROR will suffice.

I think that it is important to come up with a mechanism that improves 
the maintainability of the Msg.properties files. Especially before they 
are translated into another language.

> 
> Positioning: The resource files were originally stored in a separate
> directory because we didn't have CWClassLoader and wanted to be able to
> override resource files with files placed in ~/.jsword. Now that we have
> a cool ClassLoader maybe we should move the resource files into the java
> source tree, and have them properly package/directory based rather than
> package/filename based as at the moment?

As you noted CWClassLoader allows for resources to be practically 
anywhere. It allows a programmer to override them by putting them in 
~/.jsword, a file with a dotted package name (anywhere along the 
classpath) or as Java originally intended, in their package.

When we were building a separate resource.jar, I thought it made sense 
to have them in a resource directory. But since we have merged that into 
a single jar per Eclipse project and since we are getting more and more 
property files, I think it makes more sense to have them in their proper 
directory. However, I will defer to Joe as he has to do the work!