Re: [hackers] [libgrapheme] Rename API functions to improve readability || Laslo Hunhold

From: Laslo Hunhold <dev_AT_frign.de>
Date: Tue, 21 Dec 2021 18:49:37 +0100

On Tue, 21 Dec 2021 01:39:23 +0600
NRK <nrk_AT_disroot.org> wrote:

Dear NRK,

> It is true that verb followed by noun is more "natural" sounding , eg.
> "Get that pen." However when it comes to functions naming, I prefer
> having the noun/object first.
>
> The reasoning here is when writing code, I don't think, "Hmm, I want
> to do something and I want that something to be done on that object."
> No, my thought process is more in line with "I have this object, and
> I want to perform this action on it."
>
> Although this probably doesn't apply in this case, but one other
> benefit of this naming scheme is that functions are grouped together
> more nicely based on what they operate on. Eg. when typing "lib_objX"
> you will get all the actions you can perform on objX.
>
> Of course, I'm not claiming that everyone else's thought process is
> the same as mine. Nor am I asking the naming to be changed in this
> case. But rather, I'm simply providing some food for thought by
> explaining my rational on why I believe having object first is better
> for function naming.

thanks for your feedback! I thought about your comment a bit.

Your reasoning makes most sense in the context of object-oriented
programming languages (where you have an object and a set of methods
defined to operate on it). However, the crucial difference here is that
we don't have different object types, but always either strings of
characters or two codepoints, and the classification by type
(character, utf8, etc.) only helps when you study the library
structure, but not when using the API itself. Given the number of code
units is small, you can still quickly see which function belongs to
which source file.

The discussed API-change is part of a bigger "plan" that will however
not come intro fruition until after version 1 is released. Until then,
though, the API should be in its final form, as I don't want to impose
any API-changes after the first release, except when it really brings
dramatic improvements.

The strongest point for easier-to-read function names is that code is
written only once and read many times (ideally). So functions you can
"read" easier always win against functions that follow a stricter
structure and may be easier to program with.

With best regards

Laslo
Received on Tue Dec 21 2021 - 18:49:37 CET