Hacker News Reader

Comment by cballard | Hacker News Reader

    outputImageProviderFromBufferWithPixelFormat:pixelsWide:pixelsHigh:baseAddress:bytesPerRow:releaseCallback:releaseContext:colorSpace:shouldColorMatch:

No, this is great! I can glance at something calling this, and, without any comments, determine immediately what each parameter is!

Note that standard formatting is to place each argument on its own line, with the colons lined up, and that Xcode does this automatically, and will autocomplete the entire nonsense. It's fairly disingenuous to line the whole thing up as if you need to type it all out.

Also, this is an API that clearly bridges to C-style data structures. Higher level APIs will have much fewer parameters.

> What’s the difference between a tap and a touch?

In Apple-land, at least, a tap is an action (touching somewhere and releasing quickly, as opposed to a swipe, etc.), and a touch is where a user's finger is currently placed.

View on HN

I couldn't agree more wrt the virtues of descriptive names. An enormous set of code comments is made redundant by the use of more descriptive names. Modern tools make it trivially easy to reproduce names of arbitrary length.

I can't see the downside, yet the author of the article acts like it should be obvious.

If I may offer the downside... :)

There exists a type of programmer who will write essentially the same lines of code over and over and over again. If you're this type of programmer, having to type long function names is extremely painful.

There exists another type of programmer who refuses to retype the same thing over and over, so instead uses some technique for reusing that code. If you're this type of programmer then long, descriptive names are preferable.

It is already mentioned: you never have to type those by hand, there is autocomplete with placeholders.

But you do have do have to read them multiple times, and while while a descriptive name is good, there is a point where you are taking things too far and causing more problems than you are solving.

If I'm reading a variable name and by the end I've forgotten the first half of it's name, the long descriptive name isn't helping me nearly as much as the author might think.

Really, the variable name has a context, and I want to evaluate it within that context. That is, within the function as named, or the class and method, what does this variable name mean.

Also mentioned: usually in these cases you have items on separate lines, aligned at co colon. So you have to read just the first line to know what it is all about.

Long names are hard to read. This makes autocompletion dangerous (I had a terrible bug where I locked the wrong of two mutexes with long, descriptive names which were too similar visually.)

A good name is short enough to read as a sign in itself, it shouldn't be parsed as a sentence.

The more code reuse there is, the less you might be using the same name, as a sister comment says - but the more names you have, and a lot of long names is really hard to read. So I disagree with sister's "downside" of "it's bad for bad programmers". It's even worse for otherwise good ones who buy into this style. (Or maybe not, maybe they just read differently from me and say Rob Pike who objected "names which are short essays about the thing they name.")

All of the names in the selector are short and easy to read, there's just a lot of them. I don't even know what the method does or what any of the parameter types, but I can make what I'd assume is a fairly accurate guess:

    outputImageProviderFromBufferWithPixelFormat:

Some kind of pixel format enumeration, probably along the lines of "[Class name of the receiver]PixelFormat". Also, the function probably returns an "OutputImageProvider", or something like that (could be a id with a protocol associated, due to "provider"). This one is longer than the others, but that's just because it contains information about what the message will return.

    pixelsWide:

The width of the output image in pixels, hopefully an NSUInteger (but sadly, probably an NSInteger, and Swift is only making this discrepancy worse).

    pixelsHigh:

Same as above.

    baseAddress:

A pointer to the buffer referenced.

    bytesPerRow:

The number of bytes per row, probably size_t?

    releaseCallback:

Something to call when the provider is released, probably a block? Actually, judging by the next parameter, probably a function pointer. Wow, this must be an old API!

    releaseContext:

An argument to pass to releaseCallback.

    colorSpace:

A color space value. Possibly an enumeration of RGB, HSV, etc., or a more complex type.

    shouldColorMatch:

While I'm not sure what color matching actually is, I do know that this parameter enables or disables it, and is of type BOOL.

I'm a big fan of Apple's descriptive and remarkably consistent APIs, but the combination does make autocomplete errors easy to make and hard to notice. For instance:

  - tableView:didSelectRowAtIndexPath:
  - tableView:didDeselectRowAtIndexPath:

If you accidentally choose the latter, the behavior seems baffling: the first tap on an item does nothing, and every tap afterwards gives you the indexPath of the previously selected item. I'm embarrassed to admit how long I spent looking at indexPath values in the debugger and thinking "this can't be happening" before realizing what actually was happening.

I made the same mistake a couple of times! Felt so stupid once I found the bug :-/

I still prefer long descriptive method names though.

These days, I format the method so that each param goes into a newline (after Xcode autocompletes it) and this helps me catch such bugs.

It's OK, but I wouldn't call it great. It's readable, but sort of hard to use. The trouble is that the interface is too flexible, more so than the underlying code, and so it's hard to know which combinations of parameters are legal. If you ask for a disallowed combination, you just get nil back and no explanation.

Edit: wrong API! This one does have a pixel format object.

It also tries to be helpful and so doesn't require all parameters. If you don't give it a data pointer, it will allocate memory for you. If you don't give it bytesPerRow, it will calculate it for you. These ought to be separate calls, not all glued together into one gigantic do-everything call.

The verbosity itself is fine, but it's symptomatic of some suboptimal API design behind it.

Though it's a C API, CGBitmapContextCreate is notorious for this.

While it doesn't address everything you're alluding to, I'm a big fan of Swift's nonnull/nullable making its way into Objective-C since some of Apple's APIs don't play well with a nil parameter (e.g., -[NSString isEqualToString:]).

Yup, I like it too.

Besides being clear w/o having to dig into references or source, it also makes 'oops, wrong variable order' bugs much less likely to occur (e.g., swapped width and height is obvious using the above, not so much if using positional args).

Seriously, if you are annoyed by the long string, in most languages you can make a short form wrapper with trivial effort and trivial (if any) runtime overhead. I don't understand the complaining.

Sometimes a long name is just a hint that the code wasn't factored enough.

For instance, the phrase "outputImageProviderFromBufferWith..." suggests that the Buffer concept should have been a separate thing (probably its own class), that OutputImageProvider could be constructed from.

Reply on news.ycombinator.com