Spot The Error

[Lawrence D'Oliveiro]

public byte[] ReceiveChunk()
/* receives a complete chunk from the connection. */
{
try
{
final byte[] ChunkHeader = new byte[8];
ReceiveAll(ChunkHeader, 0, 8);
final int ChunkLength =
ChunkHeader[4]
|
ChunkHeader[5] << 8
|
ChunkHeader[6] << 16
|
ChunkHeader[7] << 24;
final byte[] TheChunk = new byte[ChunkLength + 8];
System.arraycopy(ChunkHeader, 0, TheChunk, 0, 8);
ReceiveAll(TheChunk, 8, ChunkLength);
return
TheChunk;
}
catch (IOException Failed)
{
throw new Error("problem receiving chunk");
} /*catch*/
} /*ReceiveChunk*/

Anybody else been there, done that...?

 

[Kevin McMurtrie]

public byte[] ReceiveChunk()
/* receives a complete chunk from the connection. */
{
try
{
final byte[] ChunkHeader = new byte[8];
ReceiveAll(ChunkHeader, 0, 8);
final int ChunkLength =
ChunkHeader[4]
|
ChunkHeader[5] << 8
|
ChunkHeader[6] << 16
|
ChunkHeader[7] << 24;
final byte[] TheChunk = new byte[ChunkLength + 8];
System.arraycopy(ChunkHeader, 0, TheChunk, 0, 8);
ReceiveAll(TheChunk, 8, ChunkLength);
return
TheChunk;
}
catch (IOException Failed)
{
throw new Error("problem receiving chunk");
} /*catch*/
} /*ReceiveChunk*/

Anybody else been there, done that...?

Improper sign extension?
Passing structured data as byte arrays through a public API?
Starting Java variables and functions with an upper case letter?
Replacing a perfectly good exception with a misleading one?
Formatting comments incorrectly so they don't appear in the IDE?
Commenting closing braces for geezers who never picked up an IDE?
Double indenting?


Many people have been there, never returned, and never posted it online.

 

[Lawrence D'Oliveiro]

Formatting comments incorrectly so they don't appear in the IDE?

Which “IDE†would that be, then?

 

[Abu Yahya]

Which “IDE†would that be, then?

He is referring to the use of Javadoc comments. Instead of

public byte[] ReceiveChunk()
/* receives a complete chunk from the connection. */


You should write

/* receives a complete chunk from the connection. */
public byte[] ReceiveChunk()


This will allow the IDE to display the comment when you hover your mouse
above references to this method.

See
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html
for more details on properly formatting Javadoc.

 

[Joshua Cranmer]

Which “IDE†would that be, then?

He is referring to the use of Javadoc comments. Instead of

public byte[] ReceiveChunk()
/* receives a complete chunk from the connection. */


You should write

/* receives a complete chunk from the connection. */

s/\/\*/\/\*\*/

And probably s/ r/ R/ for good measure as well...

 

[Arne Vajhøj]

Which “IDE†would that be, then?

He is referring to the use of Javadoc comments. Instead of

public byte[] ReceiveChunk()
/* receives a complete chunk from the connection. */


You should write

/* receives a complete chunk from the connection. */
public byte[] ReceiveChunk()


This will allow the IDE to display the comment when you hover your mouse
above references to this method.

See
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html
for more details on properly formatting Javadoc.

I think you are missed a *.

Arne

 

[Abu Yahya]

In message<[email protected]>, Kevin McMurtrie
wrote:

Formatting comments incorrectly so they don't appear in the IDE?

Which “IDE†would that be, then?

He is referring to the use of Javadoc comments. Instead of

public byte[] ReceiveChunk()
/* receives a complete chunk from the connection. */


You should write

/* receives a complete chunk from the connection. */
public byte[] ReceiveChunk()


This will allow the IDE to display the comment when you hover your mouse
above references to this method.

See
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html

for more details on properly formatting Javadoc.

I think you are missed a *.

Yes, I did. My bad.

It should be:

/** receives a complete chunk from the connection. */
public byte[] ReceiveChunk()

 

[Lew]

I think you are missed a *.

Yes, I did. My bad.

It should be:

/** receives a complete chunk from the connection. */
public byte[] ReceiveChunk()

You missed Joshua's remark:

s/\/\*/\/\*\*/

And probably s/ r/ R/ for good measure as well...

You also missed the entire rest of the Javadoc comment.

Tsk, tsk.

/**
* Receive a complete chunk from the connection.
* @return byte [] chunk.
*/
public byte [] receiveChunk()
...

 

[markspace]

/**
* Receive a complete chunk from the connection.
* @return byte [] chunk.
*/
public byte [] receiveChunk()

Wow, now that actually looks like Java. Unlike what the OP posted,
which I think was lisp or something.

 

[Lawrence D'Oliveiro]

Which “IDE†would that be, then?

He is referring to the use of Javadoc comments. Instead of

public byte[] ReceiveChunk()
/* receives a complete chunk from the connection. */


You should write

/* receives a complete chunk from the connection. */
public byte[] ReceiveChunk()


This will allow the IDE to display the comment when you hover your mouse
above references to this method.

Why can’t this “IDE†handle the more natural style?

 

[Arved Sandstrom]

In message<[email protected]>, Kevin McMurtrie
wrote:

Formatting comments incorrectly so they don't appear in the IDE?

Which “IDE†would that be, then?

He is referring to the use of Javadoc comments. Instead of

public byte[] ReceiveChunk()
/* receives a complete chunk from the connection. */


You should write

/* receives a complete chunk from the connection. */
public byte[] ReceiveChunk()


This will allow the IDE to display the comment when you hover your mouse
above references to this method.

Why can’t this “IDE†handle the more natural style?

There is nothing more natural about having method/function comments
after the signature than before it. Assuming this is what you meant. And
it just so happens that in most languages I've run across there is a
strong tendency to have method/function comments precede the code that
they describe.

Again, assuming that this is what you meant, you might as well get used
to source documentation tools (including their use by IDEs) requiring a
specific location for rich comments. It's not just Java and Javadoc; C#
does it with /// XML doc comments; Haddock for Haskell (and recommended
style for Haskell code comments in non-Haddock-annotated Haskell) does
it as well.

Assuming "natural" locations completely falls flat on its face for a
bunch of other things, like Java annotations or C# attributes. Usually
it's convenient or necessary to decide on a standard location for such
things, so as to make the work of the processor easier or possible. But
making such a choice doesn't make a location more "natural".

I wonder where you concluded that function/method comments are more
"natural" after a function/method signature than before it? That's not
the case in C or C++ or Pascal either. About the only language that
comes to my mind that follows your convention is Eiffel.

AHS

 

[Lew]

He is referring to the use of Javadoc comments. Instead of

public byte[] ReceiveChunk()
/* receives a complete chunk from the connection. */


You should write

/* receives a complete chunk from the connection. */
public byte[] ReceiveChunk()


This will allow the IDE to display the comment when you hover your mouse
above references to this method.

Why can’t this “IDE†handle the more natural style?

There is nothing more natural about having method/function comments after the
signature than before it. Assuming this is what you meant. And it just so
happens that in most languages I've run across there is a strong tendency to
have method/function comments precede the code that they describe.

Again, assuming that this is what you meant, you might as well get used to
source documentation tools (including their use by IDEs) requiring a specific
location for rich comments. It's not just Java and Javadoc; C# does it with
/// XML doc comments; Haddock for Haskell (and recommended style for Haskell
code comments in non-Haddock-annotated Haskell) does it as well.

Assuming "natural" locations completely falls flat on its face for a bunch of
other things, like Java annotations or C# attributes. Usually it's convenient
or necessary to decide on a standard location for such things, so as to make
the work of the processor easier or possible. But making such a choice doesn't
make a location more "natural".

I wonder where you concluded that function/method comments are more "natural"
after a function/method signature than before it? That's not the case in C or
C++ or Pascal either. About the only language that comes to my mind that
follows your convention is Eiffel.

Javadoc comments have to precede the item they document. (Abu's post did not
illustrate Javadoc comments but should have. "Lawrence D'Oliveiro" would have
known this had he read [and understood] the other posts in response to Abu's.)
"Lawrence D'Oliveiro" would have known this had he read (and understood)
any elementary documentation on the matter.

 

[Andreas Leitgeb]

final byte[] ChunkHeader = new byte[8];
ReceiveAll(ChunkHeader, 0, 8);
final int ChunkLength =
ChunkHeader[4] |
ChunkHeader[5] << 8 |
ChunkHeader[6] << 16 |
ChunkHeader[7] << 24;

I bet, you will see some wrong values more often than
correct values, that way.

byte is a signed type, and for doing math on them, they are
sign-preservingly extended to int.

So, if you got a byte of bit-pattern 10101010 at index 4, then
you get an int-value of 11111111111111111111111110101010 to which
you're then going to "or" further bits.

Anybody else been there, done that...?

Yep. But I prefer to write parsers for binary formats in Tcl, where
I just write: binary scan $ChunkHeader "a4i" ChunkName ChunkLength.

If forced to do it in Java, then change each ChunkHeader[#]
to (ChunkHeader[#] & 0xff)

 

[Arne Vajhøj]

In message<[email protected]>, Kevin McMurtrie
wrote:

Formatting comments incorrectly so they don't appear in the IDE?

Which “IDE†would that be, then?

He is referring to the use of Javadoc comments. Instead of

public byte[] ReceiveChunk()
/* receives a complete chunk from the connection. */


You should write

/* receives a complete chunk from the connection. */
public byte[] ReceiveChunk()


This will allow the IDE to display the comment when you hover your mouse
above references to this method.

Why can’t this “IDE†handle the more natural style?

It is more common to have comments before. Whether common
implies natural is pretty subjective.

But it does not matter. javadoc is a program, program expects
input in a certain format, javadoc expects comments
before, this is well documented, in fact it should be
in every Java beginner book.

Arne

 

[Lew]

They do handle the more natural style.

It is more common to have comments before. Whether common
implies natural is pretty subjective.

But it does not matter. javadoc is a program, program expects
input in a certain format, javadoc expects comments
before, this is well documented, in fact it should be
in every Java beginner book.

One might, should one want actual facts and not simply to try to
foment argument, read the Javadoc docs:
http://download.oracle.com/javase/6/docs/technotes/guides/javadoc/index.html

and of course there's,
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html
which tells us flat out, "[a] doc comment is written in HTML and must
precede a class, field, constructor or method declaration. It is made
up of two parts -- a description followed by block tags."

Of course, truth and documentation are for people who want knowledge
and skill, not those just trying to argue.

 

[Lawrence D'Oliveiro]

final byte[] ChunkHeader = new byte[8];
ReceiveAll(ChunkHeader, 0, 8);
final int ChunkLength =
ChunkHeader[4] |
ChunkHeader[5] << 8 |
ChunkHeader[6] << 16 |
ChunkHeader[7] << 24;

I bet, you will see some wrong values more often than
correct values, that way.

It would actually run for 2-3 weeks typically between crashes.

I think leaving out unsigned integer types from Java was a big mistake.

Yep. But I prefer to write parsers for binary formats in Tcl, where
I just write: binary scan $ChunkHeader "a4i" ChunkName ChunkLength.

I used Tcl once, when I was taking my first steps in GUI programming on
Linux. Then I discovered Python, and dropped Tcl like a hot stone.

 

[Lawrence D'Oliveiro]

On 2/21/2011 7:22 AM, Lawrence D'Oliveiro wrote:

In message<[email protected]>, Kevin McMurtrie
wrote:

Formatting comments incorrectly so they don't appear in the IDE?

Which “IDE†would that be, then?

He is referring to the use of Javadoc comments. Instead of

public byte[] ReceiveChunk()
/* receives a complete chunk from the connection. */


You should write

/* receives a complete chunk from the connection. */
public byte[] ReceiveChunk()


This will allow the IDE to display the comment when you hover your mouse
above references to this method.

Why can’t this “IDE†handle the more natural style?

There is nothing more natural about having method/function comments
after the signature than before it.

Except that sentence expects its subject to come at the start.

Again, assuming that this is what you meant, you might as well get used
to source documentation tools (including their use by IDEs) requiring a
specific location for rich comments.

My “source documentation tools†ARE the comments.

Here’s one of my more complex examples (in Python):

def ProjectNumberListList \
(
Prompt,
# to display next to the list (may contain HTML markup)
FormName,
# the name of the form for use in generated JavaScript
PostListDef,
# additional HTML to go after project list (e.g. fields showing
# info about currently-selected project)
SelectedProject = None,
# the ID of a project to preselect; if None, defaults to current value of CGI parameter.
ProjectGroupVarName = None,
# optional name of JavaScript variable to be assigned table of project group IDs
ProjectNameVarName = None,
# optional name of JavaScript variable to be assigned table of project names
ProjectContextVarName = None,
# optional name of JavaScript variable to be assigned table of project dialout contexts
ProjectEnabledVarName = None,
# optional name of JavaScript variable to be assigned table of project-enabled flags
ProjectPredictiveVarName = None,
# optional name of JavaScript variable to be assigned table of predictive-enabled flags
ProjectCallRefusalsVarName = None,
# optional name of JavaScript variable to be assigned table of call-refusals-enabled flags
ListsVarName = None,
# optional name of JavaScript variable to be assigned table of number list names by project
ListsEnabledVarName = None,
# optional name of JavaScript variable to be assigned table of number-list-enabled flags
# by project
PrimaryFieldsVarName = None,
# optional name of JavaScript variable to be assigned table of primary field names
RefreshCall = None, # optional JavaScript sequence intended to initialize project-list display
) :
# outputs HTML allowing the user to choose a project, and also choose
# from the available number lists already in that project.

Assuming "natural" locations completely falls flat on its face for a
bunch of other things, like Java annotations or C# attributes.

But those aren’t comments.

 

[markspace]

Prompt,
# to display next to the list (may contain HTML markup)

<http://www.python.org/dev/peps/pep-0008/>

Block Comments

Block comments generally apply to *some (or all) code that follows*
them, and are indented to the same level as that code. Each line of a
block comment starts with a # and a single space (unless it is indented
text inside the comment).

Paragraphs inside a block comment are separated by a line containing a
single #.

 

[markspace]

I think leaving out unsigned integer types from Java was a big mistake.

I think the reasons for leaving out most unsigned types were and are
sound. However I think bytes should have been unsigned like char.

Hindsight is easy though.

 

[Andreas Leitgeb]

I used Tcl once, when I was taking my first steps in GUI programming on
Linux. Then I discovered Python, and dropped Tcl like a hot stone.

That's fun. I also tried to get into Python once.
I was disappointed by that it didn't have a general for-loop
(that thing with ini,cond,incr&body parts), and when I asked
about it in comp.lang.python, they treated me similar to how
they treated you here for asking for ordered boolean: claiming
that no one would ever really need it, and offering work-arounds
even much uglier than bool?1:0. This, and the fact that editors
rarely have a feature to bring me to start/end of current block
with python's sense of a block, while giving me some handy key-
strokes to find next outer open or close brace, made me drop
python like a hot stone. And this, although I liked the then-new
generators (co-routines).