Path: csiph.com!eternal-september.org!feeder.eternal-september.org!mx02.eternal-september.org!.POSTED!not-for-mail From: Martin Gregorie Newsgroups: comp.lang.java.programmer Subject: Re: Never using booleans as parameters Date: Mon, 30 Nov 2015 00:08:12 -0000 (UTC) Organization: A noiseless patient Spider Lines: 70 Message-ID: References: <87lh9tysy8.fsf@Equus.decebal.nl> <564f55e3$0$23775$e4fe514c@news.xs4all.nl> <565310cd$0$23766$e4fe514c@news.xs4all.nl> <9993c30e-bbd7-4a87-82c9-de208d61cf39@googlegroups.com> Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Injection-Date: Mon, 30 Nov 2015 00:08:12 -0000 (UTC) Injection-Info: mx02.eternal-september.org; posting-host="e5160e2be48f1ea550cf61512446f525"; logging-data="1497"; mail-complaints-to="abuse@eternal-september.org"; posting-account="U2FsdGVkX1/5RMAT4lwX6X1aC9/yIL3NwsX2IFnR98A=" User-Agent: Pan/0.139 (Sexual Chocolate; GIT bf56508 git://git.gnome.org/pan2) Cancel-Lock: sha1:tsmXUNA0zfcKQK6Sn5OhOocx3p0= Xref: csiph.com comp.lang.java.programmer: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 |