Found in 2 comments on Hacker News
bipson · 2021-06-18 · Original thread
I can relate to where the author is coming from.

What these comments do is give the code structure, and giving an outsider a better/faster view into the code, when he has no internal model for the library/framework/API/language which helps him recognize the statements (this outsider might be the author himself, or "future me").

Not knowing what these lines do, I can at first glance (i.e. skimming through the code) understand the author's intentions, what each line is responsible for. This is simply reduction of mental load and I even do this just for myself when trying to wrap my head around a new library or language.

On the other hand, if you are writing for a (large) internal codebase, where you need to find a tradeoff between reduction of mental load and bloat, such comments can quickly become a nuisance...

Then again, the cost of useless comment is usually much smaller than the cost of mental load (everyone knows how to ignore comments, unless they fill pages...)

All this being said, I can only recommend "The Art of Readable Code" - Boswell [1].

[1] https://www.oreilly.com/library/view/the-art-of/978144931848...

klibertp · 2015-03-26 · Original thread
> The alias is just adding confusion. If I see such an alias in code, I would wonder where else that function is used in the function, and be confused that it isn't

You'd be confused once or twice, then you'd learn the technique and you'd stop being confused. Every code pattern was unfamiliar to you at first. And confusing, until you internalized it. It's unrealistic to assume that you can ever stop learning new patterns - try switching to another language and you immediately have dozens of unfamiliar, confusing patterns to learn. (it gets better after a certain amount of languages known (like https://klibert.pl/articles/programming_langs.html) because you start noticing meta-patterns)

My C is rather rusty nowadays and using function pointer here may not be the best option, but as someone else said, there are other language tools for doing this kind of aliasing, like #define. I'd go for function pointer probably, because it reveals not only a name, but also a type of function and it's guaranteed not to escape the current scope (unless explicitly returned) while #define has no knowledge of scopes at all. In languages which support real macros, and preferably lexically scoped macros (like Racket) I'd use those. In languages with closures and first-class functions I'd probably do it in yet another way. But in general, if I find myself working with a name so long that it makes it hard to spot other names on the same line I will alias it locally.

Have you read http://shop.oreilly.com/product/9780596802301.do ? It's a good, short book on the topic and it discusses exactly this issue at length in one of the chapters.