docs: add notes about method naming

[rodmax]

Try to extract rationale part from https://www.yegor256.com/2018/08/22/builders-and-manipulators.html to naming.md due to maintainer of this repo mostly followed it

...and may be search for another approaches

[harunou]

how to align

interface Bookshelf {
   books(): Book[];
   setBooks(books: Book[]): void
}

to the article?

[rodmax]

@harunou, the interface you suggested is good enough from point of my understanding of the article

could you please point me what is confusing you?

p.s. i personally have difficulties when it comes to asynchronous queries like

books(): Promise<Book[]>
vs
loadBooks(): Promise<Book[]>

right now i use loadBooks() name but not sure if this is correct

[harunou]

As mentioned in the article

Methods like saveFile() or getTitle() don’t fit and must be renamed and refactored

Thus method

setBooks(books: Book[]): void

should be renamed, but for me the name is good enough as well.

In typed language i don't think prefix load is required for async queries. Type layer already clarifies way how list of books will be delivered.

[rodmax]

:thinking: i'm not sure about saveFile() but getTitle() should be renamed to title()

Article just says

• name actions as verb
• and builders(query) as noun

and article not comments how many camelCase worlds should be in the method name so setBooks() looks good if returned void

i guess saveFile() return file descriptor or file object so author recommends name it file()

In typed language i don't think prefix load is required for async queries

here i disagree, type system say you about promise, but it not say about load or create locally

[rodmax]

another defender of our theory with Egor

Regarding this discussion

method/function name is

Noun

Use nouns as method name when method returns value but not changed state or makes side effects

Names of methods should not say anything about the implementation. After all, if you changed the implementation, would you care to rename the method?

Method name should say "what does this return"

The second place to look is the client code. In complex expressions noun-methods feels more like an English sentence.

if ( findIndex(A,t) < 0 ) then // BAD
if ( indexOf(A,t) < 0 ) then // GOOD

Verb

The main quote of above article is

I would consider a verb command name only if the dominant purpose of the function is not what it returns but how it changes the state of the world.

[rodmax]

and even more shorter

One of the more universal, yet simple rules is: Function names should be verbs if the function changes the state of the program, and nouns if they're used to return a certain value.

[rodmax]

And the finally winner candidate https://swift.org/documentation/api-design-guidelines/#strive-for-fluent-usage

It's may exceptions from Egor approach but looks promising