When describing parameters of a function/method in documentation or a blog post, I’ve noticed that I’ve naturally arrived at a particular notation, which I would like to share. For lack of a name that I know of, let’s call this notation “NoT”. It stands for Name or Type.

Example

fields(Eachable1, pat)

• fields is the function/method name
• Eachable1 is the type of the first parameter
• pat is the name of the second parameter, a pattern. Yes, pattern would be clearer but that’s a real example from the standard library.

Notation

NoT “works” in Next Generation Shell (NGS) because it builds on the existing conventions:

• Types’ names are capitalized.
• Parameters’ names are not capitalized.

Therefore, either type or the name can be used in the same context without confusion.

The notation is:

• For parameters where the name of the parameter is not important, capitalized parameter’s type is used and the parameter name is omitted. In our example parameter’s type is Eachable1. It’s usually the case for required positional parameters that the name is not important.
• Where parameter name is “interesting” or where parameter type doesn’t give enough of a clue, parameter name is used and the type is omitted. In our example it’s pat (for pattern). I argue that fields(Eachable1, pat) is better than fields(Eachable1, Any).
• In rare cases where both parameter’s name and type are important, the syntax of the language can be used as is – param_name:ParamType. (not shown in examples).

Note that some other languages are not following capitalization convention for types and I assume NoT notation wouldn’t “work” there.

More Examples

filter(Dir, pattern)
flat_map(Eachable1, Fun)
assert(val, pattern, Exception)
ensure(Int, NumRange)

Takeaway

If your situation allows, please consider adopting this notation. Or maybe it will inspire similar notations, where less important details are also omitted.

I would like to encourage you to also publish notations that you use but that are not well known.

Related Reading

• Python positional-only parameters handling. Unfortunately for NGS, the mess of parameter handling was “borrowed” from Python before that. The solution was not adopted though – looking for better solutions because def f(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2): doesn’t look good to me and also having positional-or-keyword parameters should not be implemented in NGS (but it’s exactly the case right now: all parameters are positional-or-keyword).
• I find it interesting how Swift does parameters. It uses “Argument Label” omission to signify that the name (argument label) is not important.
• Lambda Lists (Lisp) have a way to specify required, optional, rest, and keyword parameters. Don’t have the time to dig but I bet these were invented decades ago. It was stupid to ignore.

---

What do you think? Let me know in comments or wherever this post will be linked from.

---

Update: Reddit discussion