Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.java.programmer > #33149 > unrolled thread

Never using booleans as parameters

Back to article view | Back to comp.lang.java.programmer

Contents

  Never using booleans as parameters Cecil Westerhof <Cecil@decebal.nl> - 2015-11-20 09:29 +0100
    Re: Never using booleans as parameters Martin Gregorie <martin@address-in-sig.invalid> - 2015-11-20 11:54 +0000
    Re: Never using booleans as parameters Eric Sosman <esosman@comcast-dot-net.invalid> - 2015-11-20 08:30 -0500
      Re: Never using booleans as parameters Eric Douglas <e.d.programmer@gmail.com> - 2015-11-20 05:57 -0800
        Re: Never using booleans as parameters Eric Sosman <esosman@comcast-dot-net.invalid> - 2015-11-20 09:17 -0500
    Re: Never using booleans as parameters Eric Douglas <e.d.programmer@gmail.com> - 2015-11-20 05:34 -0800
    Re: Never using booleans as parameters Silvio <silvio@internet.com> - 2015-11-20 18:18 +0100
      Re: Never using booleans as parameters Eric Sosman <esosman@comcast-dot-net.invalid> - 2015-11-20 16:08 -0500
        Re: Never using booleans as parameters Silvio <silvio@internet.com> - 2015-11-23 14:12 +0100
          Re: Never using booleans as parameters Silvio <silvio@internet.com> - 2015-11-23 14:23 +0100
            Re: Never using booleans as parameters Eric Sosman <esosman@comcast-dot-net.invalid> - 2015-11-23 08:42 -0500
              Re: Never using booleans as parameters Silvio <silvio@internet.com> - 2015-11-23 15:14 +0100
          Re: Never using booleans as parameters Eric Douglas <e.d.programmer@gmail.com> - 2015-11-23 06:10 -0800
            Re: Never using booleans as parameters Arne Vajhøj <arne@vajhoej.dk> - 2015-11-29 15:45 -0500
              Re: Never using booleans as parameters Martin Gregorie <martin@address-in-sig.invalid> - 2015-11-30 00:08 +0000
                Re: Never using booleans as parameters Arne Vajhøj <arne@vajhoej.dk> - 2015-11-29 19:32 -0500
                Re: Never using booleans as parameters Arne Vajhøj <arne@vajhoej.dk> - 2015-11-29 19:39 -0500
                Re: Never using booleans as parameters Brixomatic <brixomatic@yahoo.com> - 2015-12-20 15:08 +0100
                  Re: Never using booleans as parameters Eric Douglas <e.d.programmer@gmail.com> - 2015-12-21 05:00 -0800
                    Re: Never using booleans as parameters Eric Sosman <esosman@comcast-dot-net.invalid> - 2015-12-21 08:53 -0500
              Re: Never using booleans as parameters Gene Wirchenko <genew@telus.net> - 2015-11-30 10:33 -0800
                Re: Never using booleans as parameters Jukka Lahtinen <jtfjdehf@hotmail.com.invalid> - 2015-12-02 15:51 +0200
        Re: Never using booleans as parameters Kevin McMurtrie <mcmurtrie@pixelmemory.us> - 2015-11-23 21:55 -0800
          Re: Never using booleans as parameters Eric Sosman <esosman@comcast-dot-net.invalid> - 2015-11-24 08:23 -0500
            Re: Never using booleans as parameters Kevin McMurtrie <mcmurtrie@pixelmemory.us> - 2015-11-27 22:52 -0800
          Re: Never using booleans as parameters Arne Vajhøj <arne@vajhoej.dk> - 2015-11-29 15:55 -0500
    Re: Never using booleans as parameters leif.roar@dimnakorr.com - 2015-11-20 11:44 -0600
      Re: Never using booleans as parameters Eric Douglas <e.d.programmer@gmail.com> - 2015-11-20 10:08 -0800
      Re: Never using booleans as parameters Arne Vajhøj <arne@vajhoej.dk> - 2015-11-22 14:03 -0500
    Re: Never using booleans as parameters Gene Wirchenko <genew@telus.net> - 2015-11-20 10:14 -0800
      Re: Never using booleans as parameters Eternal Hope <laughingspam99@gmail.com> - 2015-11-22 14:27 +0000
    Re: Never using booleans as parameters Kevin McMurtrie <mcmurtrie@pixelmemory.us> - 2015-11-20 20:13 -0800
      Re: Never using booleans as parameters Eric Douglas <e.d.programmer@gmail.com> - 2015-11-23 04:59 -0800
        Re: Never using booleans as parameters Arne Vajhøj <arne@vajhoej.dk> - 2015-11-29 15:53 -0500
    Re: Never using booleans as parameters galt_57@hotmail.com - 2015-11-22 09:02 -0800
      Re: Never using booleans as parameters Arne Vajhøj <arne@vajhoej.dk> - 2015-11-22 12:20 -0500
    Re: Never using booleans as parameters Arne Vajhøj <arne@vajhoej.dk> - 2015-11-22 12:41 -0500
      Re: Never using booleans as parameters Martin Gregorie <martin@address-in-sig.invalid> - 2015-11-22 18:06 +0000
      Re: Never using booleans as parameters Gene Wirchenko <genew@telus.net> - 2015-11-25 14:21 -0800
        Re: Never using booleans as parameters Arne Vajhøj <arne@vajhoej.dk> - 2015-11-29 15:58 -0500
          Re: Never using booleans as parameters Gene Wirchenko <genew@telus.net> - 2015-11-30 10:39 -0800
      Re: Never using booleans as parameters Brixomatic <brixomatic@yahoo.com> - 2015-11-29 16:40 +0100
        Re: Never using booleans as parameters Arne Vajhøj <arne@vajhoej.dk> - 2015-11-29 16:00 -0500
          Re: Never using booleans as parameters Arne Vajhøj <arne@vajhoej.dk> - 2015-11-29 19:26 -0500
            Re: Never using booleans as parameters Eric Douglas <e.d.programmer@gmail.com> - 2015-11-30 06:16 -0800
    Re: Never using booleans as parameters Arne Vajhøj <arne@vajhoej.dk> - 2015-11-22 14:01 -0500
    Re: Never using booleans as parameters Fredrik Jonson <fredrik@jonson.org> - 2015-11-24 18:50 +0000
    Re: Never using booleans as parameters Sir Hugh Jarce <hugh@example.com> - 2015-11-27 10:07 +0000
      Re: Never using booleans as parameters Arne Vajhøj <arne@vajhoej.dk> - 2015-11-29 15:49 -0500
    Re: Never using booleans as parameters Brixomatic <brixomatic@yahoo.com> - 2015-11-29 16:33 +0100
      Re: Never using booleans as parameters Eric Sosman <esosman@comcast-dot-net.invalid> - 2015-11-29 15:57 -0500
        Re: Never using booleans as parameters Arne Vajhøj <arne@vajhoej.dk> - 2015-11-29 16:01 -0500
        Re: Never using booleans as parameters Brixomatic <brixomatic@yahoo.com> - 2015-12-20 15:00 +0100
          Re: Never using booleans as parameters Gene Wirchenko <genew@telus.net> - 2015-12-21 10:50 -0800
      Re: Never using booleans as parameters Gene Wirchenko <genew@telus.net> - 2015-11-30 10:48 -0800
        Re: Never using booleans as parameters Brixomatic <brixomatic@yahoo.com> - 2015-12-20 15:44 +0100
          Re: Never using booleans as parameters Gene Wirchenko <genew@telus.net> - 2015-12-21 10:56 -0800
          Re: Never using booleans as parameters Eric Sosman <esosman@comcast-dot-net.invalid> - 2015-12-21 15:30 -0500
            Re: Never using booleans as parameters Eric Douglas <e.d.programmer@gmail.com> - 2015-12-21 12:47 -0800
              Re: Never using booleans as parameters Eric Sosman <esosman@comcast-dot-net.invalid> - 2015-12-21 16:29 -0500

Page 1 of 3  [1] 2 3  Next page →

#33149 — Never using booleans as parameters

Often is said that you should never use booleans as parameters. But I
have a function compareObjects that takes two objects and a boolean
that signifies if the function is verbose. (Sends logging.)

I could of-course define compareObjects and compareObjectsVerbose and
instead of writing:
    compareObjects(a, b, useVerbose);
I could write:
    if (useVerbose) {
        compareObjectsVerbose(a, b);
    } else {
        compareObjects(a, b);
    }

But I do not find that cleaner code. But that could because I am not
used to it. Would the second manner be better?

-- 
Cecil Westerhof
Senior Software Engineer
LinkedIn: http://www.linkedin.com/in/cecilwesterhof

[toc] | [next] | [standalone]

#33152

On Fri, 20 Nov 2015 09:29:35 +0100, Cecil Westerhof wrote:

> Often is said that you should never use booleans as parameters. But I
> have a function compareObjects that takes two objects and a boolean that
> signifies if the function is verbose. (Sends logging.)
> 
> I could of-course define compareObjects and compareObjectsVerbose and
> instead of writing:
>     compareObjects(a, b, useVerbose);
> I could write:
>     if (useVerbose) {
>         compareObjectsVerbose(a, b);
>     } else {
>         compareObjects(a, b);
>     }
> 
> But I do not find that cleaner code. But that could because I am not
> used to it. Would the second manner be better?

I have a debug class (ReportError) which takes a debug level via a 
setDebug(int verbosity) method where verbosity 0 means no debugging, and 
successively higher levels mean more verbosity. I normally set the 
verbosity level from the command line of the program being debugged. The 
basic debugging methods are: 

trace(String)   
   - generates output to stderr

trace(level, values to be traced,...)   
   - generates output to stderr if verbosity >= level 

istraceable(level) 
   - returns true or false. Used to control whether a set of
     trace(string) trace statements should be executed

error(String)
   - used to terminate the program with an error message

warn(String)
   - used to output a warning and continue


ReportError can either generate stderr output immediately or simply write 
output to a circular buffer which is output immediately before the text 
of a warn() or error() call. This can be very useful when debugging rare 
events in a very long-running program.
   
I normally declare one ReportError instance per program and pass its 
reference as a constructor argument to all classes that support debugging.

This is a class I've had around for a very long time: it was originally 
developed in C and, because I was used to having it, it got ported across 
when I started to write Java.


-- 
martin@   | Martin Gregorie
gregorie. | Essex, UK
org       |

[toc] | [prev] | [next] | [standalone]

#33154

On 11/20/2015 3:29 AM, Cecil Westerhof wrote:
> Often is said that you should never use booleans as parameters. But I
> have a function compareObjects that takes two objects and a boolean
> that signifies if the function is verbose. (Sends logging.)
>
> I could of-course define compareObjects and compareObjectsVerbose and
> instead of writing:
>      compareObjects(a, b, useVerbose);
> I could write:
>      if (useVerbose) {
>          compareObjectsVerbose(a, b);
>      } else {
>          compareObjects(a, b);
>      }
>
> But I do not find that cleaner code. But that could because I am not
> used to it. Would the second manner be better?

     Somebody forgot to tell the authors of the Java SE classes
about this prohibition ...

     When writing a method (or constructor) that takes a boolean
parameter, I'd agree that the writer should probably consider whether
there's a better design.  Perhaps there should be two methods?  Or
maybe two implementations of one interface?  Or possibly the boolean
should be an enum instead?

     But if the boolean still feels good after consideration, I'd say
go ahead and use it.  As a user of the resulting class, would you
rather write

	if (thing.isSafe()) {
	    thing.clearSafe();
	} else {
	    thing.setSafe();
	}

or

	thing.setSafe(!thing.isSafe());

?  (In a case like this, I often write all three methods. YMMV.)

-- 
esosman@comcast-dot-net.invalid
"Don't be afraid of work. Make work afraid of you." -- TLM

[toc] | [prev] | [next] | [standalone]

#33157

On Friday, November 20, 2015 at 8:30:57 AM UTC-5, Eric Sosman wrote:
> ?  (In a case like this, I often write all three methods. YMMV.)

instead of writing: 
    compareObjects(a, b, useVerbose); 
I could write: 
    if (useVerbose) { 
        compareObjectsVerbose(a, b); 
    } else { 
        compareObjects(a, b); 
    } 

If I can think of use cases where either way could be more efficient to call I'd write it both ways and tie them together so the actual code is only in there once.


public void compareObjects(Object a, Object b, boolean useVerbose) {
    if (useVerbose) { 
        compareObjectsVerbose(a, b); 
    } else { 
        compareObjects(a, b); 
    } 
}

public void compareObjects(Object a, Object b) {
}

public void compareObjectsVerbose(Object a, Object b) {
}

Then it depends what the verbose flag actually does to change the code.  compareObjectsVerbose could end up calling compareObjects, or they could both call a new private method for common code.

[toc] | [prev] | [next] | [standalone]

#33158

On 11/20/2015 8:57 AM, Eric Douglas wrote:
> On Friday, November 20, 2015 at 8:30:57 AM UTC-5, Eric Sosman wrote:
>> ?  (In a case like this, I often write all three methods. YMMV.)
>
> instead of writing:
>      compareObjects(a, b, useVerbose);
> I could write:
>      if (useVerbose) {
>          compareObjectsVerbose(a, b);
>      } else {
>          compareObjects(a, b);
>      }
>
> If I can think of use cases where either way could be more efficient to call I'd write it both ways and tie them together so the actual code is only in there once.
>
>
> public void compareObjects(Object a, Object b, boolean useVerbose) {
>      if (useVerbose) {
>          compareObjectsVerbose(a, b);
>      } else {
>          compareObjects(a, b);
>      }
> }
>
> public void compareObjects(Object a, Object b) {
> }
>
> public void compareObjectsVerbose(Object a, Object b) {
> }
>
> Then it depends what the verbose flag actually does to change the code.  compareObjectsVerbose could end up calling compareObjects, or they could both call a new private method for common code.

     Exactly.  Or, there's the other arrangement:

	public void compareObjects(Object a, Object b, boolean verbose)
	{
	    // all the code is here
	}

	public void compareObjects(Object a, Object b) {
	    compareObjects(a, b, false);
	}

	public void compareObjectsVerbose(Object a, Object b) {
	    compareObjects(a, b, true);
	}

-- 
esosman@comcast-dot-net.invalid
"Don't be afraid of work. Make work afraid of you." -- TLM

[toc] | [prev] | [next] | [standalone]

#33155

On Friday, November 20, 2015 at 3:44:11 AM UTC-5, Cecil Westerhof wrote:
> Often is said that you should never use booleans as parameters. But I
> have a function compareObjects that takes two objects and a boolean
> that signifies if the function is verbose. (Sends logging.)
> 
> I could of-course define compareObjects and compareObjectsVerbose and
> instead of writing:
>     compareObjects(a, b, useVerbose);
> I could write:
>     if (useVerbose) {
>         compareObjectsVerbose(a, b);
>     } else {
>         compareObjects(a, b);
>     }
> 
> But I do not find that cleaner code. But that could because I am not
> used to it. Would the second manner be better?

The third thing to consider is could this method be called repeatedly or could this verbosity be referenced in another method.  You could save a class variable isVerbose set to false by default, just use the compareObjects(a,b) method, and have a separate setVerbose(boolean) method.

Typically I try to consider the use case.  If my method has a yes/no question, is all the code in the method going to be in the if or the else?  Does an object calling your method typically need to use verbose just sometimes or would it typically hard code to call one method that is either verbose or not?  If you answered sometimes they'll want the verbose it should probably be a parameter.  If they could typically not want the verbose it should probably be an overload.

It's all a matter of style + convenience.  Which way is more consistent with other methods in the API?  Which way could lead to less code?  You don't want to hard code a yes method and a no method if anyone calling the method is going to call it multiple times and need an if statement every time, unless you add a super method setAlwaysVerbose(boolean).

[toc] | [prev] | [next] | [standalone]

#33160

On 11/20/2015 06:17 PM, Stefan Ram wrote:
> Cecil Westerhof <Cecil@decebal.nl> writes:
>> compareObjects(a, b, useVerbose);
>
>    That's alright. Just don't use boolean
>    literals, such as:
>
>        compareObjects( a, b, false );
>
>    . Instead write:
>
>        { final boolean verbose = false;
>          compareObjects( a, b, verbose ); }
>
>    .
>

WTF??? Please explain!

[toc] | [prev] | [next] | [standalone]

#33165

On 11/20/2015 12:18 PM, Silvio wrote:
> On 11/20/2015 06:17 PM, Stefan Ram wrote:
>> Cecil Westerhof <Cecil@decebal.nl> writes:
>>> compareObjects(a, b, useVerbose);
>>
>>    That's alright. Just don't use boolean
>>    literals, such as:
>>
>>        compareObjects( a, b, false );
>>
>>    . Instead write:
>>
>>        { final boolean verbose = false;
>>          compareObjects( a, b, verbose ); }
>>
>>    .
>>
>
> WTF??? Please explain!

     It adds a tiny bit of self-documentation.  It's not as
"solid" as a two-valued enum, but as a halfway measure ...

     Sometimes, a plain `boolean' is enough documentation:

	JFrame frame = ...;
	...
	frame.setVisible(true);  // not much doubt here

     Sometimes, the boolean's meaning is not so clear:

	HTMLEditorKit.Parser parser = ...;
	Reader reader = ...;
	HTMLEditorKit.ParserCallback callback = ...;
	parser.parse(reader, callback, false);  // WTF?

     The third argument to parse() would have been better as an
enum -- but Java didn't have enum's when that API was written.
Cecil Westerhof's suggestion could help:

	static final boolean IGNORE_CHAR_SET = true;
	... as above, then ...
	parser.parse(reader, callback, !IGNORE_CHAR_SET);

Someone looking at this would have a better chance of understanding
it than someone who saw only the `false' literal.  (Alternatively,
or in addition, you might define a false-valued ENFORCE_CHAR_SET.)

     It's not that different from using static final `int' values:

	frame.setDefaultCloseOperation(2);

Quickly, now: What option has been chosen?


S

P

O

I

L

E

R



S

P

A

C

E


	frame.setDefaultCloseOperation(DISPOSE_ON_CLOSE);

is, I think you'll agree, much more readable -- and if a descriptive
name can make an `int' more readable, why not a `boolean'?

-- 
esosman@comcast-dot-net.invalid
"Don't be afraid of work. Make work afraid of you." -- TLM

[toc] | [prev] | [next] | [standalone]

#33182

On 11/20/2015 10:08 PM, Eric Sosman wrote:
> On 11/20/2015 12:18 PM, Silvio wrote:
>> On 11/20/2015 06:17 PM, Stefan Ram wrote:
>>> Cecil Westerhof <Cecil@decebal.nl> writes:
>>>> compareObjects(a, b, useVerbose);
>>>
>>>    That's alright. Just don't use boolean
>>>    literals, such as:
>>>
>>>        compareObjects( a, b, false );
>>>
>>>    . Instead write:
>>>
>>>        { final boolean verbose = false;
>>>          compareObjects( a, b, verbose ); }
>>>
>>>    .
>>>
>>
>> WTF??? Please explain!
>
>      It adds a tiny bit of self-documentation.  It's not as
> "solid" as a two-valued enum, but as a halfway measure ...
>
>      Sometimes, a plain `boolean' is enough documentation:
>
>      JFrame frame = ...;
>      ...
>      frame.setVisible(true);  // not much doubt here
>
>      Sometimes, the boolean's meaning is not so clear:
>
>      HTMLEditorKit.Parser parser = ...;
>      Reader reader = ...;
>      HTMLEditorKit.ParserCallback callback = ...;
>      parser.parse(reader, callback, false);  // WTF?
>
>      The third argument to parse() would have been better as an
> enum -- but Java didn't have enum's when that API was written.
> Cecil Westerhof's suggestion could help:
>
>      static final boolean IGNORE_CHAR_SET = true;
>      ... as above, then ...
>      parser.parse(reader, callback, !IGNORE_CHAR_SET);
>
> Someone looking at this would have a better chance of understanding
> it than someone who saw only the `false' literal.  (Alternatively,
> or in addition, you might define a false-valued ENFORCE_CHAR_SET.)
>
>      It's not that different from using static final `int' values:
>
>      frame.setDefaultCloseOperation(2);
>
> Quickly, now: What option has been chosen?
>
>
> S
>
> P
>
> O
>
> I
>
> L
>
> E
>
> R
>
>
>
> S
>
> P
>
> A
>
> C
>
> E
>
>
>      frame.setDefaultCloseOperation(DISPOSE_ON_CLOSE);
>
> is, I think you'll agree, much more readable -- and if a descriptive
> name can make an `int' more readable, why not a `boolean'?
>

That same argument could be made for every parameter to every method 
call. So instead of

y = x.substring(0,4)

I am supposed to write

{
	final int beginIndex = 0;
	final int endIndex = 4;
	y = x.substring(beginIndex,endIndex);
}

as if Java is not verbose enough already?

If you want this vote for named parameters like they exist in Scala. And 
IMHO you do not want this: it is one of the few features Scala 
introduced that I do not use and even dislike. I also rarely see the 
feature being used in Scala code posted on the web.

[toc] | [prev] | [next] | [standalone]

#33183

On 11/23/2015 02:12 PM, Silvio wrote:
> On 11/20/2015 10:08 PM, Eric Sosman wrote:
>> On 11/20/2015 12:18 PM, Silvio wrote:
>>> On 11/20/2015 06:17 PM, Stefan Ram wrote:
>>>> Cecil Westerhof <Cecil@decebal.nl> writes:
>>>>> compareObjects(a, b, useVerbose);
>>>>
>>>>    That's alright. Just don't use boolean
>>>>    literals, such as:
>>>>
>>>>        compareObjects( a, b, false );
>>>>
>>>>    . Instead write:
>>>>
>>>>        { final boolean verbose = false;
>>>>          compareObjects( a, b, verbose ); }
>>>>
>>>>    .
>>>>
>>>
>>> WTF??? Please explain!
>>
>>      It adds a tiny bit of self-documentation.  It's not as
>> "solid" as a two-valued enum, but as a halfway measure ...
>>
>>      Sometimes, a plain `boolean' is enough documentation:
>>
>>      JFrame frame = ...;
>>      ...
>>      frame.setVisible(true);  // not much doubt here
>>
>>      Sometimes, the boolean's meaning is not so clear:
>>
>>      HTMLEditorKit.Parser parser = ...;
>>      Reader reader = ...;
>>      HTMLEditorKit.ParserCallback callback = ...;
>>      parser.parse(reader, callback, false);  // WTF?
>>
>>      The third argument to parse() would have been better as an
>> enum -- but Java didn't have enum's when that API was written.
>> Cecil Westerhof's suggestion could help:
>>
>>      static final boolean IGNORE_CHAR_SET = true;
>>      ... as above, then ...
>>      parser.parse(reader, callback, !IGNORE_CHAR_SET);
>>
>> Someone looking at this would have a better chance of understanding
>> it than someone who saw only the `false' literal.  (Alternatively,
>> or in addition, you might define a false-valued ENFORCE_CHAR_SET.)
>>
>>      It's not that different from using static final `int' values:
>>
>>      frame.setDefaultCloseOperation(2);
>>
>> Quickly, now: What option has been chosen?
>>
>>
>> S
>>
>> P
>>
>> O
>>
>> I
>>
>> L
>>
>> E
>>
>> R
>>
>>
>>
>> S
>>
>> P
>>
>> A
>>
>> C
>>
>> E
>>
>>
>>      frame.setDefaultCloseOperation(DISPOSE_ON_CLOSE);
>>
>> is, I think you'll agree, much more readable -- and if a descriptive
>> name can make an `int' more readable, why not a `boolean'?
>>
>
> That same argument could be made for every parameter to every method
> call. So instead of
>
> y = x.substring(0,4)
>
> I am supposed to write
>
> {
>      final int beginIndex = 0;
>      final int endIndex = 4;
>      y = x.substring(beginIndex,endIndex);
> }
>
> as if Java is not verbose enough already?
>
> If you want this vote for named parameters like they exist in Scala. And
> IMHO you do not want this: it is one of the few features Scala
> introduced that I do not use and even dislike. I also rarely see the
> feature being used in Scala code posted on the web.
>

My remark was targeted at the orignal example where the meaning of the 
PARAMETER is documented. Your last example aims to document the 
parameter VALUE which is pointless for boolean parameters since these 
are self-documenting values. For integer parameters that could/should 
have been enums I agree with your point. But the documentation should be 
done at the API (by either using enums or if the API is old adding named 
int constants) and certainly not at the use site.

[toc] | [prev] | [next] | [standalone]

#33184

On 11/23/2015 8:23 AM, Silvio wrote:
> [...]
> My remark was targeted at the orignal example where the meaning of the
> PARAMETER is documented. Your last example aims to document the
> parameter VALUE which is pointless for boolean parameters since these
> are self-documenting values. [...]

     Sometimes, sometimes not.  I gave an example of each.

> [...] For integer parameters that could/should
> have been enums I agree with your point. But the documentation should be
> done at the API (by either using enums or if the API is old adding named
> int constants) and certainly not at the use site.

     For reference purposes, the meaning (and purpose) of every
parameter should certainly be documented.  No disagreement there.

     For readability, additional in-code hints can be helpful at
the point of use.  When somebody reading the code sees

	thing.method(otherThing, true);

... he can always drop what he's doing, open up the Javadoc, hunt
around through the various overloads of method() until he finds
the right one (oh, it's inherited from a superclass, gotta switch
to a different Javadoc page), ...  He can eventually find what
`true' means in this situation.  And then he can say, "All right,
now, uh, where was I?"

     On the other hand, if he sees

	thing.method(otherThing, ALLOW_DUPLICATIONS);

... I maintain that there's a significantly better chance he won't
need to disrupt his train of thought to rummage through the docs.
If he's unfamiliar with the API, yes, he'll still need to read
them to comprehend what "duplications" are supposed to be, and
what the consequences of "allowing" them are -- but if he's not
familiar with the API he'll need to read the docs anyhow.  Assuming
he's got some passing familiarity, `ALLOW_DUPLICATIONS' is a good
deal more understandable than `true'.

     As I've said before (and am perhaps over-fond of saying), there
are two audiences for source code: Computers and people, and the
latter merit more consideration than the former.

-- 
esosman@comcast-dot-net.invalid
"Don't be afraid of work. Make work afraid of you." -- TLM

[toc] | [prev] | [next] | [standalone]

#33186

On 11/23/2015 02:42 PM, Eric Sosman wrote:
> On 11/23/2015 8:23 AM, Silvio wrote:
>> [...]
>> My remark was targeted at the orignal example where the meaning of the
>> PARAMETER is documented. Your last example aims to document the
>> parameter VALUE which is pointless for boolean parameters since these
>> are self-documenting values. [...]
>
>      Sometimes, sometimes not.  I gave an example of each.
>
>> [...] For integer parameters that could/should
>> have been enums I agree with your point. But the documentation should be
>> done at the API (by either using enums or if the API is old adding named
>> int constants) and certainly not at the use site.
>
>      For reference purposes, the meaning (and purpose) of every
> parameter should certainly be documented.  No disagreement there.
>
>      For readability, additional in-code hints can be helpful at
> the point of use.  When somebody reading the code sees
>
>      thing.method(otherThing, true);
>
> ... he can always drop what he's doing, open up the Javadoc, hunt
> around through the various overloads of method() until he finds
> the right one (oh, it's inherited from a superclass, gotta switch
> to a different Javadoc page), ...  He can eventually find what
> `true' means in this situation.  And then he can say, "All right,
> now, uh, where was I?"
>
>      On the other hand, if he sees
>
>      thing.method(otherThing, ALLOW_DUPLICATIONS);
>
> ... I maintain that there's a significantly better chance he won't
> need to disrupt his train of thought to rummage through the docs.
> If he's unfamiliar with the API, yes, he'll still need to read
> them to comprehend what "duplications" are supposed to be, and
> what the consequences of "allowing" them are -- but if he's not
> familiar with the API he'll need to read the docs anyhow.  Assuming
> he's got some passing familiarity, `ALLOW_DUPLICATIONS' is a good
> deal more understandable than `true'.
>
>      As I've said before (and am perhaps over-fond of saying), there
> are two audiences for source code: Computers and people, and the
> latter merit more consideration than the former.
>

I maintain he will need to lookup what thing.method does, regardless of 
the parameter list. Unless he is familiar with the API, in which case he 
should know both the method and the meaning of the parameters.

Using well chosen identifiers and using properly named constants instead 
of magic numbers is all we should do in source code. All additional 
attempts to document code should be done by adding remarks and not 
purposely adding redundant code like in the example Stefan gave.

I think we all consider only people when talking about source code 
readability.

[toc] | [prev] | [next] | [standalone]

#33185

On Monday, November 23, 2015 at 8:12:59 AM UTC-5, Silvio wrote:
> That same argument could be made for every parameter to every method 
> call. So instead of
> 
> y = x.substring(0,4)
> 
> I am supposed to write
> 
> {
> 	final int beginIndex = 0;
> 	final int endIndex = 4;
> 	y = x.substring(beginIndex,endIndex);
> }

You could do that, or write it with a comment as such, only if the meaning of the parameters would not be obvious to someone asked to maintain your code later.

// beginIndex (zero-based), endIndex
y = x.substring(0,4)

Of course they should already be able to figure out the parameters from the code complete if they edit this code with a proper IDE.  It would seem more important to make the parameters clear on the other end.  I can't recall offhand where the worst offenders are but I have had to work with APIs where the code complete for their methods shows nothing but (String arg0, String arg1).  It would appear someone at Google is correcting this, as one example I have where my IDE calls the parameters arg0 and arg1, the Javadoc on the web now calls them content and mediaContent.

[toc] | [prev] | [next] | [standalone]

#33227

On 11/23/2015 9:10 AM, Eric Douglas wrote:
> On Monday, November 23, 2015 at 8:12:59 AM UTC-5, Silvio wrote:
>> That same argument could be made for every parameter to every method
>> call. So instead of
>>
>> y = x.substring(0,4)
>>
>> I am supposed to write
>>
>> {
>> 	final int beginIndex = 0;
>> 	final int endIndex = 4;
>> 	y = x.substring(beginIndex,endIndex);
>> }
>
> You could do that, or write it with a comment as such, only if the
 > meaning of the parameters would not be obvious to someone asked to
 > maintain your code later.
>
> // beginIndex (zero-based), endIndex
> y = x.substring(0,4)

Documenting something like this is an indication of a problem
in my opinion.

Commenting about what the code does is usually a bad sign - good
comments explains why the code is doing it.

> Of course they should already be able to figure out the parameters
> from the code complete if they edit this code with a proper IDE.

A good IDE solves many problems.

But I don't like the idea of the readability of code
being dependent on it.

Arne

[toc] | [prev] | [next] | [standalone]

#33236

On Sun, 29 Nov 2015 15:45:39 -0500, Arne Vajhøj wrote:

> On 11/23/2015 9:10 AM, Eric Douglas wrote:
>> On Monday, November 23, 2015 at 8:12:59 AM UTC-5, Silvio wrote:
>>> That same argument could be made for every parameter to every method
>>> call. So instead of
>>>
>>> y = x.substring(0,4)
>>>
>>> I am supposed to write
>>>
>>> {
>>> 	final int beginIndex = 0;
>>> 	final int endIndex = 4;
>>> 	y = x.substring(beginIndex,endIndex);
>>> }
>>
>> You could do that, or write it with a comment as such, only if the
>  > meaning of the parameters would not be obvious to someone asked to
>  > maintain your code later.
>>
>> // beginIndex (zero-based), endIndex y = x.substring(0,4)
> 
> Documenting something like this is an indication of a problem in my
> opinion.
> 
> Commenting about what the code does is usually a bad sign - good
> comments explains why the code is doing it.
> 
>> Of course they should already be able to figure out the parameters from
>> the code complete if they edit this code with a proper IDE.
> 
> A good IDE solves many problems.
> 
> But I don't like the idea of the readability of code being dependent on
> it.
> 
> Arne


IMO well-written code *always* has a class-level comment saying what 
functionality the class provides and  method-level comments for every 
method. The method-level comments say what the method does, what 
parameters are passed to it and what they mean, what it returns and how 
it indicates that errors have been detected. 

IOW, if a system designer writes a class specification as a compilable 
Java source file containing a class-level comment followed by public 
constructor and method definitions, each being a comment as I've 
described above followed by a skeleton method (completed header with the 
body containing only the appropriate return statement), a coder can flesh 
this out by adding the required code to the methods so that the class 
fulfils its required functions as well as any additional private 
attributes or methods that the class requires. The result is a functional 
class that is also fully documented.

And, before you ask, yes I've used this approach for projects implemented 
in both Java and C. It works. The only overhead is that the designers 
*MUST* compile their module specifications to verify that the interfaces 
they've specified form a consistent set.

I have little respect for any software architect who can't do this and 
not much for any technical or project manager who doesn't require his 
designers to work to this standard.


-- 
martin@   | Martin Gregorie
gregorie. | Essex, UK
org       |

[toc] | [prev] | [next] | [standalone]

#33238

On 11/29/2015 7:08 PM, Martin Gregorie wrote:
> On Sun, 29 Nov 2015 15:45:39 -0500, Arne Vajhøj wrote:
>
>> On 11/23/2015 9:10 AM, Eric Douglas wrote:
>>> You could do that, or write it with a comment as such, only if the
>>   > meaning of the parameters would not be obvious to someone asked to
>>   > maintain your code later.
>>>
>>> // beginIndex (zero-based), endIndex y = x.substring(0,4)
>>
>> Documenting something like this is an indication of a problem in my
>> opinion.
>>
>> Commenting about what the code does is usually a bad sign - good
>> comments explains why the code is doing it.

> IMO well-written code *always* has a class-level comment saying what
> functionality the class provides and  method-level comments for every
> method. The method-level comments say what the method does, what
> parameters are passed to it and what they mean, what it returns and how
> it indicates that errors have been detected.

That is rather standard.

It is comments explaining what statements does that smells.

Classic horror code:

// for all elements in array va
for(int v : va) {
    // if v is greater than zero
    if(v > 0) {
        ...
    }
}

Using comments to explain what method arguments are (note: in
the calling code) is almost as bad in my opinion.

Arne

[toc] | [prev] | [next] | [standalone]

#33239

On 11/29/2015 7:08 PM, Martin Gregorie wrote:
> IOW, if a system designer writes a class specification as a compilable
> Java source file containing a class-level comment followed by public
> constructor and method definitions, each being a comment as I've
> described above followed by a skeleton method (completed header with the
> body containing only the appropriate return statement), a coder can flesh
> this out by adding the required code to the methods so that the class
> fulfils its required functions as well as any additional private
> attributes or methods that the class requires. The result is a functional
> class that is also fully documented.

> I have little respect for any software architect who can't do this and
> not much for any technical or project manager who doesn't require his
> designers to work to this standard.

It is one approach, but there are other.

You can explicit document classes and methods using UML class diagrams.

You can implicit document classes and methods by unit test cases (TDD).

Your approach is a bit more detailed. But I am not fully convinced
that is a benefit. For an awful large part of the code it will
take longer time to write the stub than write the method content.
The ratio of system designer/architect/tech lead hours to
software developer implementation hours could be impractically big.
As a consequence I would be tempted to only use such an approach for
the most important parts of the exposed interface.

Arne

[toc] | [prev] | [next] | [standalone]

#33372

In article <n3g41b$1ep$1@dont-email.me>, Martin Gregorie 
(martin@address-in-sig.invalid) says...
> 
> On Sun, 29 Nov 2015 15:45:39 -0500, Arne Vajhøj wrote:
> 
> > On 11/23/2015 9:10 AM, Eric Douglas wrote:
> >> On Monday, November 23, 2015 at 8:12:59 AM UTC-5, Silvio wrote:
> >>> That same argument could be made for every parameter to every method
> >>> call. So instead of
> >>>
> >>> y = x.substring(0,4)
> >>>
> >>> I am supposed to write
> >>>
> >>> {
> >>> 	final int beginIndex = 0;
> >>> 	final int endIndex = 4;
> >>> 	y = x.substring(beginIndex,endIndex);
> >>> }
> >>
> >> You could do that, or write it with a comment as such, only if the
> >  > meaning of the parameters would not be obvious to someone asked to
> >  > maintain your code later.
> >>
> >> // beginIndex (zero-based), endIndex y = x.substring(0,4)
> > 
> > Documenting something like this is an indication of a problem in my
> > opinion.
> > 
> > Commenting about what the code does is usually a bad sign - good
> > comments explains why the code is doing it.
> > 
> >> Of course they should already be able to figure out the parameters from
> >> the code complete if they edit this code with a proper IDE.
> > 
> > A good IDE solves many problems.
> > 
> > But I don't like the idea of the readability of code being dependent on
> > it.
> > 
> > Arne
> 
> 
> IMO well-written code *always* has a class-level comment saying what 
> functionality the class provides and  method-level comments for every 
> method. The method-level comments say what the method does, what 
> parameters are passed to it and what they mean, what it returns and how 
> it indicates that errors have been detected. 

/** Represents a point in a 2 dimensional space.*/
class Point2D{
 private double x; //the x coordinate
 private double y; //the y coordinate


 /** Sets the x coordinate
 * @param x a double value representing the x coordinate of the point.
 */
 public void setX(double x){this.x=x;}

 /** Sets the x coordinate
 * @param y a double value representing the y coordinate of the point.
 */
 public void setY(double y){this.y=y;}

}

Diagnosis: 
Programmer has wasted time and money blindly following a style guide.

Kind regards,
Wanja

-- 
..Alesi's problem was that the back of the car was jumping up and down 
dangerously - and I can assure you from having been teammate to 
Jean Alesi and knowing what kind of cars that he can pull up with, 
when Jean Alesi says that a car is dangerous - it is. [Jonathan Palmer]

[toc] | [prev] | [next] | [standalone]

#33375

On Sunday, December 20, 2015 at 9:08:22 AM UTC-5, Brixomatic wrote:
>  /** Sets the x coordinate
>  * @param y a double value representing the y coordinate of the point.
>  */
>  public void setY(double y){this.y=y;}
> 
> }

Half the program bugs are caused by this sort of copy and paste.

I hate writing documentation lines to describe what a method does which ought to be self documenting, but my OCD doesn't like seeing documentation lines on only half the methods.

[toc] | [prev] | [next] | [standalone]

#33378

On 12/21/2015 8:31 AM, Stefan Ram wrote:
> Eric Douglas <e.d.programmer@gmail.com> writes:
>> On Sunday, December 20, 2015 at 9:08:22 AM UTC-5, Brixomatic wrote:
>>>   /** Sets the x coordinate
>>>   * @param y a double value representing the y coordinate of the point.
>>>   */
>>>   public void setY(double y){this.y=y;}
>> I hate writing documentation lines to describe what a method
>> does which ought to be self documenting, but my OCD doesn't
>> like seeing documentation lines on only half the methods.
>
>    The client is not supposed to read the source code of
>    the implementation of the method, but only the header.

     Did you, perhaps, overlook the crucial point?  The mistake
is not in the executable source code, but in what you call the
"header" (newsgroup confusion?), that is, in exactly the part
the client is intended and expected to read.

-- 
esosman@comcast-dot-net.invalid
"Don't be afraid of work. Make work afraid of you." -- TLM

[toc] | [prev] | [next] | [standalone]

Page 1 of 3  [1] 2 3  Next page →

Back to top | Article view | comp.lang.java.programmer

csiph-web