Re: [racket-users] API function naming
The prefixes are based on this file: https://github.com/racket/gui/blob/master/tex-table/tex-table.rkt Maybe there are missing ones you're used to? Sorry, that was supposed to be a compliment! I love DrRacket's support for unicode and I havent wanted any symbols that aren't already supported. I was agreeing with Neil V's general sentiment that inputting non-standard symbols (even with DrRacket's assistance) often feels more cumbersome than simply choosing a longer name. It's like the right-handed version of emacs pinky? However, ultimately I stick with the shorter names because I agree that it's more readable. Robby -- You received this message because you are subscribed to the Google Groups Racket Users group. To unsubscribe from this group and stop receiving emails from it, send an email to racket-users+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout. -- You received this message because you are subscribed to the Google Groups Racket Users group. To unsubscribe from this group and stop receiving emails from it, send an email to racket-users+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
[racket-users] API function naming
I am using a cmd-name! naming format for functions that are adding to the command list that will be communicated to the host program. (cmd-sound! WAV-FILE) (cmd-set-position! pos yaw-radians) Etc. I am considering using a terser naming convention, perhaps @name, so you would have: (@sound WAV-FILE) (@set-position pos yaw-radians) Etc. I would argue that while they do mutate global state by sticking something on a list, the list is never looked at except at the very end of the frame to hand it over to the host system, so they are more like a display / log function that a global state hazard, and having a syntax cue for functions that are going to impact the sensory presentation may be useful. Thoughts? What symbols have the least historic baggage? -- You received this message because you are subscribed to the Google Groups Racket Users group. To unsubscribe from this group and stop receiving emails from it, send an email to racket-users+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
Re: [racket-users] API function naming
You also have unicode available to you. IDE support can help with this -- I think the cmd-\ for lambda has worked pretty well. I've been going this route more, especially because DrRacket supports autocompletion of (what it deems) unique latex prefixes. For example, in DrRacket, type \G, followed by ctrl-\ However, I often hate myself afterwards, exactly because: These punctuation characters that typically require a shift modifier might be pleasing to the eye, but unpleasing to the typist. That being said, I haven't stopped doing it yet. Robby On Fri, Jul 3, 2015 at 12:36 PM, Stephen Chang stch...@ccs.neu.edu wrote: What symbols have the least historic baggage? I've gone through this exercise a few times, and each time settled on '$'. As Greg points out, pretty much every one of my my Racket libraries makes use of this symbol (was it that obvious? :) ) exactly because I was looking for something that Racket programmers would not confuse for something else. Off the top of my head, here are some other Racket symbol conventions (may not apply to Scheme in general): ~: syntax-parse pattern combinators; I've tried to use this before and received negative feedback about it !: imperative/side-effecting functions @: documentation, at mentioned by Greg, and also units #: recognized by the reader (often in combination with a second symbol) for various literals %: objects, and % is for interfaces (as a suffix) ^: unit signatures (suffix) : this one may be relatively safe, I think? *: sometimes denotes list version or more often just alternate (eg let*) -: standard word delimiter, a la '_' in C and other languages /: often pronounced with, as in call/cc; can also just be a delimiter (eg in the web server) _: the C ffi bindings have this prefix; some use it to mean internal ?: predicates (suffix) =: equality functions (suffix) Did I miss any? Note that I excluded symbols that already have special meaning to the reader: http://docs.racket-lang.org/reference/reader.html (Should these go in the style guide somewhere?) Another idea is to use two or more symbols? -- You received this message because you are subscribed to the Google Groups Racket Users group. To unsubscribe from this group and stop receiving emails from it, send an email to racket-users+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout. -- You received this message because you are subscribed to the Google Groups Racket Users group. To unsubscribe from this group and stop receiving emails from it, send an email to racket-users+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout. -- You received this message because you are subscribed to the Google Groups Racket Users group. To unsubscribe from this group and stop receiving emails from it, send an email to racket-users+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout. -- You received this message because you are subscribed to the Google Groups Racket Users group. To unsubscribe from this group and stop receiving emails from it, send an email to racket-users+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
RE: [racket-users] API function naming
I tried $ first, but it scans so close to an S that it hurt readability. -Original Message- From: Greg Hendershott [mailto:greghendersh...@gmail.com] Sent: Friday, July 03, 2015 11:53 AM To: John Carmack Cc: racket-users@googlegroups.com Subject: Re: [racket-users] API function naming One idea is to use $ as prefix. It probably connotes command among Unix-y folks, at least. (Although I've seen $ used as a prefix in e.g. combinator libraries like Parsack, I don't think it has any universal meaning like that which would make it seem weird for your purposes?) On Fri, Jul 3, 2015 at 12:41 PM, Greg Hendershott greghendersh...@gmail.com wrote: I'd avoid @ because it's used for at-expressions, e.g. #lang scribble or even simply #lang at-exp racket. On Fri, Jul 3, 2015 at 12:32 PM, John Carmack jo...@oculus.com wrote: I am using a “cmd-name!” naming format for functions that are adding to the command list that will be communicated to the host program. (cmd-sound! WAV-FILE) (cmd-set-position! pos yaw-radians) Etc. I am considering using a terser naming convention, perhaps “@name”, so you would have: (@sound WAV-FILE) (@set-position pos yaw-radians) Etc. I would argue that while they do mutate global state by sticking something on a list, the list is never looked at except at the very end of the frame to hand it over to the host system, so they are more like a display / log function that a global state hazard, and having a syntax cue for functions that are going to impact the sensory presentation may be useful. Thoughts? What symbols have the least historic baggage? -- You received this message because you are subscribed to the Google Groups Racket Users group. To unsubscribe from this group and stop receiving emails from it, send an email to racket-users+unsubscr...@googlegroups.com. For more options, visit https://urldefense.proofpoint.com/v1/url?u=https://groups.google.com/d/optoutk=ZVNjlDMF0FElm4dQtryO4A%3D%3D%0Ar=Kjg6LltY9QjkipKooaVldA%3D%3D%0Am=3sT2b8Ee4ORHnImx7YLz8vXTDIljXVXZTGVhfs2xyPM%3D%0As=999028754ff1a2cbad33512421e2e5c7c1f27b6448cbb0ea4ca14c43f84d4ff5. -- You received this message because you are subscribed to the Google Groups Racket Users group. To unsubscribe from this group and stop receiving emails from it, send an email to racket-users+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
Re: [racket-users] API function naming
What symbols have the least historic baggage? I've gone through this exercise a few times, and each time settled on '$'. As Greg points out, pretty much every one of my my Racket libraries makes use of this symbol (was it that obvious? :) ) exactly because I was looking for something that Racket programmers would not confuse for something else. Off the top of my head, here are some other Racket symbol conventions (may not apply to Scheme in general): ~: syntax-parse pattern combinators; I've tried to use this before and received negative feedback about it !: imperative/side-effecting functions @: documentation, at mentioned by Greg, and also units #: recognized by the reader (often in combination with a second symbol) for various literals %: objects, and % is for interfaces (as a suffix) ^: unit signatures (suffix) : this one may be relatively safe, I think? *: sometimes denotes list version or more often just alternate (eg let*) -: standard word delimiter, a la '_' in C and other languages /: often pronounced with, as in call/cc; can also just be a delimiter (eg in the web server) _: the C ffi bindings have this prefix; some use it to mean internal ?: predicates (suffix) =: equality functions (suffix) Did I miss any? Note that I excluded symbols that already have special meaning to the reader: http://docs.racket-lang.org/reference/reader.html (Should these go in the style guide somewhere?) Another idea is to use two or more symbols? -- You received this message because you are subscribed to the Google Groups Racket Users group. To unsubscribe from this group and stop receiving emails from it, send an email to racket-users+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout. -- You received this message because you are subscribed to the Google Groups Racket Users group. To unsubscribe from this group and stop receiving emails from it, send an email to racket-users+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
Re: [racket-users] API function naming
I'd avoid @ because it's used for at-expressions, e.g. #lang scribble or even simply #lang at-exp racket. On Fri, Jul 3, 2015 at 12:32 PM, John Carmack jo...@oculus.com wrote: I am using a “cmd-name!” naming format for functions that are adding to the command list that will be communicated to the host program. (cmd-sound! WAV-FILE) (cmd-set-position! pos yaw-radians) Etc. I am considering using a terser naming convention, perhaps “@name”, so you would have: (@sound WAV-FILE) (@set-position pos yaw-radians) Etc. I would argue that while they do mutate global state by sticking something on a list, the list is never looked at except at the very end of the frame to hand it over to the host system, so they are more like a display / log function that a global state hazard, and having a syntax cue for functions that are going to impact the sensory presentation may be useful. Thoughts? What symbols have the least historic baggage? -- You received this message because you are subscribed to the Google Groups Racket Users group. To unsubscribe from this group and stop receiving emails from it, send an email to racket-users+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout. -- You received this message because you are subscribed to the Google Groups Racket Users group. To unsubscribe from this group and stop receiving emails from it, send an email to racket-users+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
Re: [racket-users] API function naming
We clearly need keyboards like this: http://9gag.com/gag/5551148/the-entire-chinese-keyboard On Fri, Jul 3, 2015 at 1:43 PM, Stephen Chang stch...@ccs.neu.edu wrote: The prefixes are based on this file: https://github.com/racket/gui/blob/master/tex-table/tex-table.rkt Maybe there are missing ones you're used to? Sorry, that was supposed to be a compliment! I love DrRacket's support for unicode and I havent wanted any symbols that aren't already supported. I was agreeing with Neil V's general sentiment that inputting non-standard symbols (even with DrRacket's assistance) often feels more cumbersome than simply choosing a longer name. It's like the right-handed version of emacs pinky? However, ultimately I stick with the shorter names because I agree that it's more readable. Robby -- You received this message because you are subscribed to the Google Groups Racket Users group. To unsubscribe from this group and stop receiving emails from it, send an email to racket-users+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout. -- You received this message because you are subscribed to the Google Groups Racket Users group. To unsubscribe from this group and stop receiving emails from it, send an email to racket-users+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
Re: [racket-users] API function naming
One idea is to use $ as prefix. It probably connotes command among Unix-y folks, at least. (Although I've seen $ used as a prefix in e.g. combinator libraries like Parsack, I don't think it has any universal meaning like that which would make it seem weird for your purposes?) On Fri, Jul 3, 2015 at 12:41 PM, Greg Hendershott greghendersh...@gmail.com wrote: I'd avoid @ because it's used for at-expressions, e.g. #lang scribble or even simply #lang at-exp racket. On Fri, Jul 3, 2015 at 12:32 PM, John Carmack jo...@oculus.com wrote: I am using a “cmd-name!” naming format for functions that are adding to the command list that will be communicated to the host program. (cmd-sound! WAV-FILE) (cmd-set-position! pos yaw-radians) Etc. I am considering using a terser naming convention, perhaps “@name”, so you would have: (@sound WAV-FILE) (@set-position pos yaw-radians) Etc. I would argue that while they do mutate global state by sticking something on a list, the list is never looked at except at the very end of the frame to hand it over to the host system, so they are more like a display / log function that a global state hazard, and having a syntax cue for functions that are going to impact the sensory presentation may be useful. Thoughts? What symbols have the least historic baggage? -- You received this message because you are subscribed to the Google Groups Racket Users group. To unsubscribe from this group and stop receiving emails from it, send an email to racket-users+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout. -- You received this message because you are subscribed to the Google Groups Racket Users group. To unsubscribe from this group and stop receiving emails from it, send an email to racket-users+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
Re: [racket-users] API function naming
You also have unicode available to you. IDE support can help with this -- I think the cmd-\ for lambda has worked pretty well. Robby On Fri, Jul 3, 2015 at 12:36 PM, Stephen Chang stch...@ccs.neu.edu wrote: What symbols have the least historic baggage? I've gone through this exercise a few times, and each time settled on '$'. As Greg points out, pretty much every one of my my Racket libraries makes use of this symbol (was it that obvious? :) ) exactly because I was looking for something that Racket programmers would not confuse for something else. Off the top of my head, here are some other Racket symbol conventions (may not apply to Scheme in general): ~: syntax-parse pattern combinators; I've tried to use this before and received negative feedback about it !: imperative/side-effecting functions @: documentation, at mentioned by Greg, and also units #: recognized by the reader (often in combination with a second symbol) for various literals %: objects, and % is for interfaces (as a suffix) ^: unit signatures (suffix) : this one may be relatively safe, I think? *: sometimes denotes list version or more often just alternate (eg let*) -: standard word delimiter, a la '_' in C and other languages /: often pronounced with, as in call/cc; can also just be a delimiter (eg in the web server) _: the C ffi bindings have this prefix; some use it to mean internal ?: predicates (suffix) =: equality functions (suffix) Did I miss any? Note that I excluded symbols that already have special meaning to the reader: http://docs.racket-lang.org/reference/reader.html (Should these go in the style guide somewhere?) Another idea is to use two or more symbols? -- You received this message because you are subscribed to the Google Groups Racket Users group. To unsubscribe from this group and stop receiving emails from it, send an email to racket-users+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout. -- You received this message because you are subscribed to the Google Groups Racket Users group. To unsubscribe from this group and stop receiving emails from it, send an email to racket-users+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout. -- You received this message because you are subscribed to the Google Groups Racket Users group. To unsubscribe from this group and stop receiving emails from it, send an email to racket-users+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
Re: [racket-users] API function naming
1. +1 on Neil's +sound and +set-position convention (as a private Racket citizen not the style guide author) 2. When I find myself writing such code now, I often write a syntactic extension that gives me some flexibility in how I want to do it: (commands (sound ...) (set-position ...) ...) which I can then expand to (let* ([L '()] [L (cons (sounds L ...) ...)] ;; -- if L is needed for context (you say it isn't) [L (cons ...)] ...) L) ;; or (send-to some-address L) Alternatively I use the obvious set! expansion. Either way hygienic expansion ensures that L isn't accidentally accessible, only to commands that need it (or none). -- Matthias On Jul 3, 2015, at 12:32 PM, John Carmack jo...@oculus.com wrote: I am using a “cmd-name!” naming format for functions that are adding to the command list that will be communicated to the host program. (cmd-sound! WAV-FILE) (cmd-set-position! pos yaw-radians) Etc. I am considering using a terser naming convention, perhaps “@name”, so you would have: (@sound WAV-FILE) (@set-position pos yaw-radians) Etc. I would argue that while they do mutate global state by sticking something on a list, the list is never looked at except at the very end of the frame to hand it over to the host system, so they are more like a display / log function that a global state hazard, and having a syntax cue for functions that are going to impact the sensory presentation may be useful. Thoughts? What symbols have the least historic baggage? -- You received this message because you are subscribed to the Google Groups Racket Users group. To unsubscribe from this group and stop receiving emails from it, send an email to racket-users+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout. -- You received this message because you are subscribed to the Google Groups Racket Users group. To unsubscribe from this group and stop receiving emails from it, send an email to racket-users+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
Re: [racket-users] API function naming
General comment on the naming conventions we come up with... These punctuation characters that typically require a shift modifier might be pleasing to the eye, but unpleasing to the typist. Incidentally, while @ might have lower typing cost than cmd-, I think it's more than 1/4 the typing cost: cmd- does have the property of being unshifted alpha-and-minus characters, and from alternating hands on a typical US QWERTY keyboard. Neil V. -- You received this message because you are subscribed to the Google Groups Racket Users group. To unsubscribe from this group and stop receiving emails from it, send an email to racket-users+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
Re: [racket-users] API function naming
On 07/03/2015 12:32 PM, John Carmack wrote: I am using a “cmd-name!” naming format for functions that are adding to the command list that will be communicated to the host program. (cmd-sound! WAV-FILE) (cmd-set-position! pos yaw-radians) Etc. I am considering using a terser naming convention, perhaps “@name”, so you would have: (@sound WAV-FILE) (@set-position pos yaw-radians) Etc. I would argue that while they do mutate global state by sticking something on a list, the list is never looked at except at the very end of the frame to hand it over to the host system, so they are more like a display / log function that a global state hazard, and having a syntax cue for functions that are going to impact the sensory presentation may be useful. Thoughts? What symbols have the least historic baggage? I was going to list the known baggage, but Stephen ninja'd me. He missed one, though, which seems to connote what you want and isn't ugly or too hard to type: (+sound WAV-FILE) (+set-position pos yaw-radians) Neil ⊥ -- You received this message because you are subscribed to the Google Groups Racket Users group. To unsubscribe from this group and stop receiving emails from it, send an email to racket-users+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
Re: [racket-users] API function naming
Alexis King wrote on 07/03/2015 06:33 PM: Perhaps this isn’t applicable in this case, but may I suggest a less-common alternative: no prefixing at all? If you put all the commands into a separate module, users of the module can use ‘prefix-in’ to choose whatever prefix they prefer. For reusable Racket packages, intended to be intermixed with other Racket packages in arbitrary programs, I think Racket actually prefers provided names to be globally unique among all packages. (Look at how documentation searches work, for example.) However, for a more closed world of a particular application (where you're providing the IDE and hardware and everything), making more generic names (e.g., `get`) do very application-specific things might be appropriate. Especially if you make your own `#lang` for it (which `#lang` would likely provide a combination of `racket/base` or `racket`, together with your generic-looking application-specific identifiers). At the same time as your `#lang`, you can separately have an application-specific reusable library intended for use with the rare Racket program that does not use your `#lang`, in which case it's more OK to make those programmers use `prefix-in` and have trouble with documentation lookups. IMHO. Neil V. -- You received this message because you are subscribed to the Google Groups Racket Users group. To unsubscribe from this group and stop receiving emails from it, send an email to racket-users+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
Re: [racket-users] API function naming
Perhaps this isn’t applicable in this case, but may I suggest a less-common alternative: no prefixing at all? If you put all the commands into a separate module, users of the module can use ‘prefix-in’ to choose whatever prefix they prefer. This can be paired with documentation that uses a particular prefix in all its examples, encouraging a standard of sorts, but the choice of any prefix would still be available if a user prefers. For an example of this in the wild see Racket’s own parser-tools library (http://docs.racket-lang.org/parser-tools/Lexers.html). The common matchers are provided unprefixed in the parser-tools/lex-sre module, but the docs consistently use a ‘:’ prefix to create a standardized usage. This doesn’t eliminate the problem of needing to choose a prefix entirely, but it does give a little more flexibility to avoid the fear of choosing a prefix some users really don’t like. Alexis -- You received this message because you are subscribed to the Google Groups Racket Users group. To unsubscribe from this group and stop receiving emails from it, send an email to racket-users+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
Re: [racket-users] API function naming
Perhaps this isn’t applicable in this case, but may I suggest a less-common alternative: no prefixing at all? If you put all the commands into a separate module, users of the module can use ‘prefix-in’ to choose whatever prefix they prefer. Prefixes (and suffixes) have two purposes. One is to disambiguate a global namespace, as with the set- or hash- functions. I think your proposal applies in this case and I mostly agree. The other purpose is to convey a (sometimes package-local) convention. For example, users of my Parsack package know that any $-prefixed identifier is a parser. Removing the prefix would defeat the readability that I'm trying to achieve, similar to removing the '?' from predicates. John's case seems to fall into the latter so I think a prefix would be useful. (And I second Neil T's suggestion.) This can be paired with documentation that uses a particular prefix in all its examples, encouraging a standard of sorts, but the choice of any prefix would still be available if a user prefers. For an example of this in the wild see Racket’s own parser-tools library (http://docs.racket-lang.org/parser-tools/Lexers.html). The common matchers are provided unprefixed in the parser-tools/lex-sre module, but the docs consistently use a ‘:’ prefix to create a standardized usage. This doesn’t eliminate the problem of needing to choose a prefix entirely, but it does give a little more flexibility to avoid the fear of choosing a prefix some users really don’t like. Alexis -- You received this message because you are subscribed to the Google Groups Racket Users group. To unsubscribe from this group and stop receiving emails from it, send an email to racket-users+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout. -- You received this message because you are subscribed to the Google Groups Racket Users group. To unsubscribe from this group and stop receiving emails from it, send an email to racket-users+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
