Reconsider the use of 2 in conversion function names

Aperta Adatta ai principianti
  • Qualcosa non va?
#7 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
2/5
Tempo stimato
1-3 ore
Idoneità per principianti
63/100
Tipo di issue
Documentazione
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
matlab
Ambito
documentation

Direzione di ricerca

Inizia dalle linee guida di codifica MATLAB del repository e individua la sezione «Function name style» citata nell’issue. Esamina la raccomandazione esistente e le alternative proposte, quindi aggiorna le linee guida se i responsabili del progetto accettano la modifica. Il lavoro è concluso quando la raccomandazione sulla denominazione delle conversioni riflette la decisione e resta coerente con le linee guida di stile circostanti.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

The MATLAB coding guidelines currently state the following under Function name style:

Name functions and methods using a verb or verb phrase to convey the action performed. Alternatively, name functions and methods using a noun or noun phrase if the noun describes the thing being created. Use the numeral "2" in the name of a conversion function. Use the prefix "is" or "has" for a function whose primary output is a logical value. Use complementary names for functions with complementary operations (e.g., start/stop, create/destroy, etc.).

I would like to suggest reconsidering the recommendation to use the numeral 2 in conversion function names.
The type2type convention feels dated and, more importantly, can reduce readability. Using 2 as a substitute for "to" makes names less natural to read and becomes particularly awkward when the type names themselves contain numbers. For example, consider:

myByte = uint82byte(myUint8);

versus:

myByte = uint8ToByte(myUint8);

or:

myByte = byteFromUint8(myUint8);

I find the last form the clearest because it reads naturally as "byte from uint8" and makes the direction of the conversion immediately apparent.
This convention also maps naturally to an object-oriented API. For example, the same operation could conceptually be expressed as:

myByte = Byte.FromUint8(myUint8);

The standalone function name byteFromUint8 follows directly from that same naming pattern.

Beyond aesthetics, avoiding 2 would also eliminate potentially confusing names such as uint82byte, where the 8 belongs to the source type and the 2 represents the word "to".
My suggestion is therefore to reconsider the requirement to use 2 for conversion functions and instead recommend descriptive conversion names such as:

  • targetFromSource, e.g. byteFromUint8
  • sourceToTarget, e.g. uint8ToByte

Of the two, I would favor targetFromSource because it emphasizes what the function produces and reads naturally at the call site.

Lingua principale
Nessun dato sulla lingua
Stelle
143
Fork
11
Nessuna PR unita negli ultimi 30g

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di mathworks/MATLAB-Coding-Guidelines

Tutte le issue di mathworks/MATLAB-Coding-Guidelines

Issue simili

Altre issue su Documentation

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.