Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]
Groups > comp.lang.java.programmer > #33184
| From | Eric Sosman <esosman@comcast-dot-net.invalid> |
|---|---|
| Newsgroups | comp.lang.java.programmer |
| Subject | Re: Never using booleans as parameters |
| Date | 2015-11-23 08:42 -0500 |
| Organization | A noiseless patient Spider |
| Message-ID | <n2v4vi$vsr$1@dont-email.me> (permalink) |
| References | (1 earlier) <boolean-20151120181620@ram.dialup.fu-berlin.de> <564f55e3$0$23775$e4fe514c@news.xs4all.nl> <n2o1vd$os2$1@dont-email.me> <565310cd$0$23766$e4fe514c@news.xs4all.nl> <56531352$0$23783$e4fe514c@news.xs4all.nl> |
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
Back to comp.lang.java.programmer | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread
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
csiph-web