Notice: In order to edit this ticket you need to be either: a Product Owner, The owner or the reporter of the ticket, or, in case of a Task not yet assigned, a team_member"

Task #12121 (new)

Opened 6 years ago

Last modified 5 years ago

Model use of Boolean values instead of enumerations

Reported by: rleigh Owned by: rleigh
Priority: major Milestone: Unscheduled
Component: Specification Version: 5.0.0
Keywords: n.a. Cc: mlinkert, jburel
Resources: n.a. Referenced By: n.a.
References: n.a. Remaining Time: n.a.
Sprint: n.a.

Description

The following attributes use Boolean values:

Pixels: BigEndian?, Interleaved
Objective: Iris
Laser: Tuneable, PockelCell?
Shape: Locked, Visible

From the modelling point of view, there is nothing wrong with Boolean values for these attributes. These do describe things perfectly well. However, from the generated API point of view, this is suboptimal. The problem is that true/false as method arguments and return values are not self-describing, and the code is not readable or self documenting. For example, consider this use of BigEndian? and Interleaved:

writer.setPixelType(UINT16, true, false);

and compare with the use of enums:

writer.setPixelType(UINT16, BIG_ENDIAN, CHUNKY)

where BIG_ENDIAN is one of the endianness enumerations, and CHUNKY is one of the interleaving enumerations.

This means that it's impossible to accidentally swap the arguments since they are specific enums where the boolean options were interchangeable. And it also means they can be used with C++ templates and Java generics as type-specific template parameters.

Suggestions for enums:

BigEndian?: change name to Endian with Big and Little enumerations [also allows for Mixed]
Interleaved: change name to Interleaving with Chunky and Planar enumerations
Iris: Add Absent and Present enumerations [more specific iris enumerations are possible]
PockelCell?: Add Absent and Present enumerations [more specific enumerations are possible]
Tuneable: change name to Tuning with None and Tunable enumerations [more specific SingleLine?, MultiLine?, NarrowBand? etc. enumerations could also be added]
Visible: change name to Visibility with Visible and Invisible enumerations
Locked: change name to Modifiable with Locked and Unlocked enumerations

Better naming is obviously possible, these are just initial suggestions.

The main points are to

  • make the API safer
  • make the code more readable
  • allow use in templates
  • allow extension of the "true" cases with finer-grained options, i.e. allowing for future extensibility

Change History (10)

Changed 6 years ago by rleigh

Changed 6 years ago by rleigh

Changed 6 years ago by rleigh

comment:1 Changed 6 years ago by rleigh

https://github.com/rleigh-dundee/bioformats/compare/spec-enums?expand=1 contains the changes to convert each boolean value to an enum, one commit per enum (also attached here). These contain everything except the upgrade transforms. We might not want to convert all of these; each commit can be applied in isolation to select specific enums. The only ones I really care about for my C++ work are the Endian and SubChannelInterleaving? enums.

One question which came up discussing this with Chris was the need for BigEndian? on BinData? given that it's already present on Pixels. What actually needs this attribute? The only other user is Mask, and without a corresponding pixel type/word size, it's not clear what BigEndian? even means in this context. Is it actually needed, or could it be moved completely over to Pixels and removed entirely from BinData??

comment:2 Changed 6 years ago by jamoore

  • Cc mlinkert jburel added
  • Priority changed from minor to major
  • Summary changed from Bug: Model use of Boolean values instead of enumerations to Model use of Boolean values instead of enumerations

We'll soon be going through bug clean-up. I'm removing "Bug:" from this since it's more of a RFE. Might be this needs a representation on trello as well.

comment:3 Changed 5 years ago by ajpatterson

  • Owner changed from ajpatterson to rleigh
Note: See TracTickets for help on using tickets. You may also have a look at Agilo extensions to the ticket.

1.3.13-PRO © 2008-2011 Agilo Software all rights reserved (this page was served in: 0.83919 sec.)

We're Hiring!