Questo dipende in gran parte dalla tua API / ambiente.
Alcune regole e linee guida che conosco:
- In generale: POLA - Principio di Almost Astonishment (prima portato a Computer Science da Mike Colishaw nel suo libro Rexx Programming Language), noto anche come Rule of Least Surprise - prova a pensare dal punto di vista di un utente API, come è facile da ricordare? Come è naturale leggere? Evita stupore / sorpresa.
- Metti insieme argomenti coerenti. Esempio: in
arraycopy(src, srcOffset, dst, dstOffest, length)
, src
e srcOffset
sono molto coerenti, quindi restano uniti. length
è anche coesivo a src
, ma è ugualmente coesivo a dst
, il che rende la coesione meno specifica, quindi viene per ultima.
- Posiziona prima l'oggetto principale, ovvero l'oggetto che sarebbe un riferimento
this
in una lingua OO. In altre parole: posiziona l'oggetto "a cui è stata data l'operazione" per primo.
- Posiziona la destinazione prima della fonte (C e lingue simili).
- Posiziona il sorgente / input prima della destinazione / output (Java e lingue simili).
- Posiziona gli argomenti che sono più propensi a variare tra chiamate di funzioni simili più a destra, quegli argomenti che hanno maggiori probabilità di rimanere gli stessi più a sinistra.
- Posiziona i parametri con un significato più generico più a sinistra, quelli con un significato più specifico più a destra. Ad esempio:
(directory, file)
di solito è più logico di (file, directory)
- a meno che directory
sia una destinazione. Oppure class, object
di solito è più logico di object, class
- a meno che object
sia di this
nature.
- Prova a rendere le chiamate leggere (quasi) come una prosa ben scritta.
E alcuni suggerimenti:
- Sii coerente con la tua API.
- Semplifica gli utenti che già conoscono API simili, ovvero guardati intorno. Se sviluppi un'estensione Qt, guarda come si sente la stessa API Qt. Se sviluppi un'API Java, guarda come appare l'API Java SUN / Oracle.
Alcuni altri esempi:
- Se una funzione accetta un array, un offset in quell'array e una lunghezza, la sequenza dovrebbe essere
(array, offset, length)
perché è così che pensi: prima cosa, poi i dettagli e i dettagli nella sequenza in cui contano . Il contratto è probabilmente relativo all'iterazione che prevediamo di iniziare con offset
ed eseguirlo fino al raggiungimento di length
.
Nel tuo caso dipende dalla natura del simbolo, dell'oggetto e della classe. Se suppongo che l'oggetto sia membro di una classe e che il simbolo sia membro di un oggetto, probabilmente mi aspetto che la sequenza sia (class, object, symbol)
.