multi-line Strings

[Arved Sandstrom]

String literal inside annotation is not equal to literal inside code. It
is like static constans - you can read it on code-buld phase ex. by
Annotation Processor.


There is good a "rule of life" . Never create literals in the code.

It's *all* code, William. As far as I am concerned, every single byte of
a *.java source file is code. Annotations absolutely are code, they are
also instructions to the computer.

AHS

 

[William Bonawentura]

Then how would you do the following?

public boolean isGetMethodName( String methodName ) {

It seems to me, that isGetMethodName is a internal part of reflecion-based library. Not a final / business / application code.

 

[William Bonawentura]

It's *all* code, William. As far as I am concerned, every single byte of a *.java source file is code. Annotations absolutely are
code, they are also instructions to the computer.

OK. Refine:

You should never create runtime computed literals inside your business code.

 

[Daniel Pitts]

OK. Refine:

You should never create runtime computed literals inside your business
code.

More refined:
You should never create an absolute rule. There are always exceptions.
Except for this rule.

It's a guideline to avoid "magic" values, but not all inline literals
are "magic".

For instance, I have seen people avoid "?" and "&" by introducing the
constants QUESTION_MARK and AMPERSAND. This is bad.

 

[markspace]

For instance, I have seen people avoid "?" and "&" by introducing the
constants QUESTION_MARK and AMPERSAND. This is bad.

I wonder, in general, where the line should be drawn? Java coding
guidelines recommend that 1 and -1 can be used as literals, but other
integer constants should defined as a "constant" by the programmer.

I'm not sure that single character strings, or characters, should be
treated the same way. I can see cases for it, and I can see reasons for
not doing so, as Daniel implies.

Here's a grab from a recent discussion on transforming \u sequences in a
Java string. This is the bit in the Properties object that scans a line
read from a properties file for special escape sequences. I don't think
that the Java source APIs are the be-all and end-all of code style, but
it is a large public body of well-reviewed code. Note the abundant use
of single character constants, with out a programmer introduced
constant. It seems to read OK to me.


while (keyLen < limit) {
c = lr.lineBuf[keyLen];
//need check if escaped.
if ((c == '=' || c == ':') && !precedingBackslash) {
valueStart = keyLen + 1;
hasSep = true;
break;
} else if ((c == ' ' || c == '\t' || c == '\f') &&
!precedingBackslash) {
valueStart = keyLen + 1;
break;
}
if (c == '\\')
precedingBackslash = !precedingBackslash;
else
precedingBackslash = false;
keyLen++;
}

 

[Gene Wirchenko]

I wonder, in general, where the line should be drawn? Java coding
guidelines recommend that 1 and -1 can be used as literals, but other
integer constants should defined as a "constant" by the programmer.

What about zero?


Why should limit myself to just one line?

I draw a line between things that are unlikely to change and
those that may well change. Yes, I know that this is still blurry.

If I were writing code to do record blocking and deblocking, I
would not use literals in the work code for the physical and logical
record lengths.

If I were writing code dealing with weeks, I might well use 7 for
the number of days in a week.

I draw another line between simple (where I am much less likely
to bother) and complex (where I am much more likely to).

If the constants are local to just one procedure/method or a
short class, I might not bother. If the constants are used in more
than one place, I almost certainly will.

I draw a third line between temporary code and permanent code.
The former, unlikely; the latter, likely.

(Make sure that your "temporary" code really is temporary.)

I'm not sure that single character strings, or characters, should be
treated the same way. I can see cases for it, and I can see reasons for
not doing so, as Daniel implies.

It depends to me on what their use is. Run-of-the-garden use, as
in the code example you posted, hardly needs it.

Here's a grab from a recent discussion on transforming \u sequences in a
Java string. This is the bit in the Properties object that scans a line
read from a properties file for special escape sequences. I don't think
that the Java source APIs are the be-all and end-all of code style, but
it is a large public body of well-reviewed code. Note the abundant use
of single character constants, with out a programmer introduced
constant. It seems to read OK to me.

Likewise to me. It is short though so it does not prove much.
Were it a couple of pages long, it would be more of a test.

[snip]

Sincerely,

Gene Wirchenko

 

[Gene Wirchenko]

I wonder, in general, where the line should be drawn? Java coding
guidelines recommend that 1 and -1 can be used as literals, but other
integer constants should defined as a "constant" by the programmer.

What about zero?


Why should limit myself to just one line?

I draw a line between things that are unlikely to change and
those that may well change. Yes, I know that this is still blurry.

If I were writing code to do record blocking and deblocking, I
would not use literals in the work code for the physical and logical
record lengths.

If I were writing code dealing with weeks, I might well use 7 for
the number of days in a week.

I draw another line between simple (where I am much less likely
to bother) and complex (where I am much more likely to).

If the constants are local to just one procedure/method or a
short class, I might not bother. If the constants are used in more
than one place, I almost certainly will.

I draw a third line between temporary code and permanent code.
The former, unlikely; the latter, likely.

(Make sure that your "temporary" code really is temporary.)

I'm not sure that single character strings, or characters, should be
treated the same way. I can see cases for it, and I can see reasons for
not doing so, as Daniel implies.

It depends to me on what their use is. Run-of-the-garden use, as
in the code example you posted, hardly needs it.

Here's a grab from a recent discussion on transforming \u sequences in a
Java string. This is the bit in the Properties object that scans a line
read from a properties file for special escape sequences. I don't think
that the Java source APIs are the be-all and end-all of code style, but
it is a large public body of well-reviewed code. Note the abundant use
of single character constants, with out a programmer introduced
constant. It seems to read OK to me.

Likewise to me. It is short though so it does not prove much.
Were it a couple of pages long, it would be more of a test.

[snip]

Sincerely,

Gene Wirchenko

 

[markspace]

I draw a line between things that are unlikely to change and
those that may well change. Yes, I know that this is still blurry.

This is my point! The line *is* blurry! And I'm not sure if any hard
and fast rules can be made. Even generalities are somewhat hard to talk
about authoritatively.

(On 0, well n+0 is a bit gauche, yes? But I'll admit that things like
array indexes or sub-string offsets, yes 0 as a literal is allowed by
Oracles guidelines, and useful.)

Likewise to me. It is short though so it does not prove much.
Were it a couple of pages long, it would be more of a test.

The whole method is longer, and also broken up into three methods and
one private class. I think it's worth looking at. There was obviously
a deliberate effort to break-down the procedure into functional units,
which I think helps the readability of the code as much as anything.
(But also makes character literals more readable as a result.)

Unfortunately, the website with JDK source code isn't showing up on my
Google searches, so I can't make a link.

 

[Jukka Lahtinen]

You missed Eric's point. You stipulated a rule - "final code does not need
to have any strings literals. Strings should be always created via
out-of-code resources". You just now broke your own rule with your

OK. How would you define the name of the file / database table /
whatever resource to hold the string literals? Would you always give it
as a command line parameter?

 

[Eric Sosman]

[...]
I wonder, in general, where the line should be drawn? Java coding
guidelines recommend that 1 and -1 can be used as literals, but other
integer constants should defined as a "constant" by the programmer.

Java coding guidelines suggest -1,0,1 can be literals,
but only in `for' loops. Use them elsewhere, or use those
values in any type other than `int', and you're supposed
to use a `static final'. That is, the guidelines frown
on `q = 1.0 - p;' and even on `System.exit(0);'.

What utter nonsense!

Let's not forget that the Java coding guidelines come
from the same minds that made `byte' signed, invented
Integer#getInteger(String), and designed java.util.Date.
Consider the source.

 

[Lew]

William Bonawentura forgot to attribute:

It seems to me, that isGetMethodName is a internal part of reflecion-based library. Not a final / business / application code.

How blazingly irrelevant, and an example of the "No True Scotsman" fallacy.

 

[Arne Vajhøj]

There is good a "rule of life" . Never create literals in the code.

As Eric has demonstrated that rule practically prevent writing a
lot of code.

Arne

 

[Arne Vajhøj]

String literal inside annotation is not equal to literal inside code. It
is like static constans - you can read it on code-buld phase ex. by
Annotation Processor.

Annotations are also code.

Arne

 

[Arne Vajhøj]

It seems to me, that isGetMethodName is a internal part of
reflecion-based library. Not a final / business / application code.

First. You just talked about "code" not this subset of code.

Second. Even with that subset of code it is not true.

Arne

 

[Arne Vajhøj]

OK. How would you define the name of the file / database table /
whatever resource to hold the string literals? Would you always give it
as a command line parameter?

I assume that question was not for Arved ...

Arne

 

[Arne Vajhøj]

IMO, about the only things (strings-wise) which really make sense being
moved into external resources are:
default configuration options (debatable, if the config file will
override them anyways);
(potentially) messages intended for human readers or similar (say, to
allow language-specific translations or similar).

I18N and CMS and templates are some pretty big cases.

if the bulk of the string literals are things internal to the program
(rather than intended for an end user), then it makes little sense to
move them to external resources (IME, most string literals tend to be
program internal anyways, with human-readable messages few and far
between, and most of these in-turn being internal debugging messages).

Even for internal usage, then reading text from external resources
due to the less testing required after a change.

And considering human-readable messages to be "few and far between"
seems pretty far from reality to me.

with user-readable strings, the program could still be developed under a
policy like "if you need the messages in a language you can read, either
learn English (or Japanese or Chinese or similar) or get a dictionary",
so making them external may not make much sense in this case.

That may not be good business.

even with language-specific strings, unless using magic numbers, a
string may still be needed to refer to them.

Of course.

Arne

 

[Arne Vajhøj]

Yes, probably, but so would using Python-like """string""" features as
was discussed recently. IMO regexes are so powerful and useful that it
would be worthwhile making them a special case, but then again I'm not a
language designer, so what do I know....

I am not so happy about special additions to language to handle
special cases.

But then I am not a language person either ...

Its just a bit frustrating that there are languages around that can deal
with regexes without turning them into an unreadable mess and that Java
isn't one of them.

The regex syntax itself is not exactly a good example of readability.

Arne

 

[Arne Vajhøj]

This is my point! The line *is* blurry! And I'm not sure if any hard
and fast rules can be made. Even generalities are somewhat hard to talk
about authoritatively.

The two main reasons to move literals to constants are:
* safer change of value, because changing the constant changes it everywhere
* better documentation by using a descriptive name

I believe one would get a decent indication of whether
to use a constant or not.

Does the same literal occur more than once where it must be the
same value?

Would the code be more readable by using a descriptive name
instead of a literal.

There are still a bit of blur, but not so bad.

Arne

 

[Arne Vajhøj]

What about zero?

It should not be the value that decide that.

The coding convention says:

<quote>
10.3 Constants

Numerical constants (literals) should not be coded directly, except for
-1, 0, and 1, which can appear in a for loop as counter values.
</quote>

so -1, 0 amd 1 are all OK but *ONLY* in only in for loops.

But it does not seem very well founded.

I draw a line between things that are unlikely to change and
those that may well change. Yes, I know that this is still blurry.

That and documentation should be the main criteria.

If I were writing code to do record blocking and deblocking, I
would not use literals in the work code for the physical and logical
record lengths.

It should not even be constants.

If I were writing code dealing with weeks, I might well use 7 for
the number of days in a week.

It depends on the context.

It will obviously not change.

But in some contexts NUMBER_DAYS_IN_WEEK will make it easier
to understand the code than 7.

I draw another line between simple (where I am much less likely
to bother) and complex (where I am much more likely to).

That seems to me to be a the readability rule.

If the constants are local to just one procedure/method or a
short class, I might not bother. If the constants are used in more
than one place, I almost certainly will.

That is the change rule.

I draw a third line between temporary code and permanent code.
The former, unlikely; the latter, likely.

Temporary code where best practices does not apply are not so
interesting to discuss.

Arne

 

[Arne Vajhøj]

[...]
I wonder, in general, where the line should be drawn? Java coding
guidelines recommend that 1 and -1 can be used as literals, but other
integer constants should defined as a "constant" by the programmer.

Java coding guidelines suggest -1,0,1 can be literals,
but only in `for' loops. Use them elsewhere, or use those
values in any type other than `int', and you're supposed
to use a `static final'. That is, the guidelines frown
on `q = 1.0 - p;' and even on `System.exit(0);'.

What utter nonsense!

It could probably have been done better.

Let's not forget that the Java coding guidelines come
from the same minds that made `byte' signed, invented
Integer#getInteger(String), and designed java.util.Date.
Consider the source.

Nobody is perfect.

Arne