Re: Guidelines/Recommendations for namespaces and qualified keywords

[Alex Miller]

On Saturday, October 15, 2016 at 10:17:15 PM UTC-5, Josh Tilles wrote:
>
> I’ve got a couple questions for Alex Miller and/or the other Cognitect 
> folks.
>
>1. *Are single-segment namespaces still “bad” when it comes to 
>registering specs under qualified keywords?*
>
> I will give a qualified *sometimes*. :) There are several possible 
contexts and I would not give the same answer for all of them. 

If you are creating a library, particularly a library that will 
interoperate with other libraries, I would strongly recommend using 
namespaced keywords with sufficient namespaces that you will not clash with 
others. In some cases, a library may be well-entrenched or well-known 
enough to make a single namespace sufficient. For example, consider ring 
request/response maps and middleware, which is a prime example for 
interoperable libraries. If you were creating a Ring session middleware, 
you might want to use namespace keys in the request like 
:ring.session/token (or whatever, don't compare this to any actual existing 
lib). Here, "ring" is probably sufficiently established to be unambiguous 
and "ring.session" scopes you to something narrower. I think that's highly 
preferable to just :ring/token. 

If you're creating a brand new library designed for interoperation with 
other libs, I would strongly consider using more than a single segment 
namespace that combines some notion of organization and project. 

If you're creating an internal application, I think you're free to do 
whatever you want. So a single segment path in the context of a single 
application might be totally fine - :domain/email. As long as you're not 
colliding with some library and you coordinate in your private scope, do 
what communicates the best for you. If you have multiple internal projects 
that need to coordinate, you might need more namespace segments to 
disambiguate.

>
>1. In the past, single-segment namespaces have been discouraged in the 
>Clojure community—both because of Java interop concerns and because of the 
>possibility of name-collision when combining projects. However, many of 
> the 
>spec examples I’ve seen have demonstrated registering specs under keywords 
>qualified by a single-segment namespace. For example, the guide’s 
>section on multi-spec  
>defines :search/url and :error/message. Is that because 
>namespace-qualifiers of specs shouldn’t be under the same constraints as 
>namespaces used to organize code? 
>
> These short names are mostly chosen to make the examples brief and 
readable, although they might be sufficient when used in an application as 
mentioned above. However, I think it is important to note that your 
namespace qualifiers do NOT need to correspond to your code. You can use 
create-ns and alias to create shorter names in the context of a particular 
namespace just to save typing, while still using namespaces independent 
from your code. We are considering changing alias to automatically create a 
ns if it does not exist (see http://dev.clojure.org/jira/browse/CLJ-2030).

>
>1. I’m *guessing* not; it seems more likely that the single-segment 
>namespaces have been used only to keep the code snippets straightforward 
>and focused on spec, and that “real” code would alias (e.g.) 
>my-company.my-project.search as search before defining a ::search/url 
>spec.
>
> Yes. 

>
>1. 
>2. *When designing, how do you decide whether to use a simple keyword 
>or a qualified one?*
>There’s an interesting mix of the two in the official docs and in the 
>code for spec itself. For example: the spec rationale 
> and guide 
> both use simple keywords 
>when labeling path components, and spec reports invocation errors for 
>instrumented functions with maps that exclusively use qualified keys at 
> the 
>“root” but simple keywords appear as values 
>
> 
>  
>and as keys in nested maps 
>
> 
>.
>
> Path components are simple as they exist in the context of a particular 
spec which has a fully-qualified name. I suspect in general the other 
choices mostly follow that pattern - fully-qualified when they are used 
without context or when they might be intermingled with other keys and 
unqualified when used as keys in the scope of some other context. That 
said, things may not be 100% consistent in every possible case.

Hope that helps!
Alex

 

> Thank you for your help. I really appreciate it.
>
> Best,
> Josh
>

-- 
You received this message because you are subscribed 

Re: Guidelines/Recommendations for namespaces and qualified keywords

[Mauricio Aldazosa]

On Mon, Oct 17, 2016 at 9:46 PM, James Gatannah 
wrote:

>
>
> On Saturday, October 15, 2016 at 10:17:15 PM UTC-5, Josh Tilles wrote:
>>
>> I’ve got a couple questions for Alex Miller and/or the other Cognitect
>> folks.
>>
>
> That isn't me. I'm just chiming in from the peanut gallery. Must of my
> "experience" so far stems from converting
> my toy projects from prismatic schema to spec.
>
>>
>>1. *Are single-segment namespaces still “bad” when it comes to
>>registering specs under qualified keywords?*
>>In the past, single-segment namespaces have been discouraged in the
>>Clojure community—both because of Java interop concerns and because of the
>>possibility of name-collision when combining projects. However, many of 
>> the
>>spec examples I’ve seen have demonstrated registering specs under keywords
>>qualified by a single-segment namespace. For example, the guide’s
>>section on multi-spec 
>>defines :search/url and :error/message. Is that because
>>namespace-qualifiers of specs shouldn’t be under the same constraints as
>>namespaces used to organize code?
>>
>> This part of the question interests me a lot.
>
> I've found myself defining a lot of specs in, say, the
> com.foo.project.schemas namespace.
>
> This used to be extremely convenient, due to ns aliases.
>
> I think the docs say that I should be able to set up the same kind of
> basic aliasing so that I can
> just refer to those specs as (for example) :c.f.p.s/whatever. But I
> haven't been able to actually
> get that to work yet.
>

You can use the alias to do that, if you have a ns declaration like this:

(ns test.core
  (:require [com.foo.project.schemas :as sch]))

Then you can use the alias to get to the specs in that namespace

::sch/bar => :com.foo.project.schemas/bar

Cheers,
Mauricio

-- 
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clojure@googlegroups.com
Note that posts from new members are moderated - please be patient with your 
first post.
To unsubscribe from this group, send email to
clojure+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
--- 
You received this message because you are subscribed to the Google Groups 
"Clojure" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Guidelines/Recommendations for namespaces and qualified keywords

[James Gatannah]

On Saturday, October 15, 2016 at 10:17:15 PM UTC-5, Josh Tilles wrote:
>
> I’ve got a couple questions for Alex Miller and/or the other Cognitect 
> folks.
>

That isn't me. I'm just chiming in from the peanut gallery. Must of my 
"experience" so far stems from converting
my toy projects from prismatic schema to spec.

>
>1. *Are single-segment namespaces still “bad” when it comes to 
>registering specs under qualified keywords?*
>In the past, single-segment namespaces have been discouraged in the 
>Clojure community—both because of Java interop concerns and because of the 
>possibility of name-collision when combining projects. However, many of 
> the 
>spec examples I’ve seen have demonstrated registering specs under keywords 
>qualified by a single-segment namespace. For example, the guide’s 
>section on multi-spec  
>defines :search/url and :error/message. Is that because 
>namespace-qualifiers of specs shouldn’t be under the same constraints as 
>namespaces used to organize code?
>
> This part of the question interests me a lot.

I've found myself defining a lot of specs in, say, the 
com.foo.project.schemas namespace.

This used to be extremely convenient, due to ns aliases.

I think the docs say that I should be able to set up the same kind of basic 
aliasing so that I can
just refer to those specs as (for example) :c.f.p.s/whatever. But I haven't 
been able to actually 
get that to work yet.

I've found myself with a lot of definitions that look like (apologies for 
the formatting/whitespace):

(s/def ::socket-description (s/keys :opt [::client-keys
  ::server-key]
:req [::ctx
  
:com.jimrthy.cljeromq.common/direction
  ::port
  ::sock-type
  
:com.jimrthy.cljeromq.common/socket
  :com.jimrthy.cljeromq.core/url]))

That isn't *too* bad. But this sort of thing gets annoying when I'm nesting 
these things into other namespaces. Especially from the REPL, which is 
lisp's strongest selling point (to me).

I'm willing to bet that I've just missed a talk somewhere about how this is 
supposed to work. Or maybe I just need to keep working on getting my head 
wrapped around these changes.

I don't want to hijack your thread. This was more of a "Me too! This is 
why...I think" sort of thing.. 




>1. I’m *guessing* not; it seems more likely that the single-segment 
>namespaces have been used only to keep the code snippets straightforward 
>and focused on spec, and that “real” code would alias (e.g.) 
>my-company.my-project.search as search before defining a ::search/url 
>spec.
>
>
> Thank you for your help. I really appreciate it.
>

Again, me too! Thanks,
James 

>
> Best,
> Josh
>

-- 
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clojure@googlegroups.com
Note that posts from new members are moderated - please be patient with your 
first post.
To unsubscribe from this group, send email to
clojure+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
--- 
You received this message because you are subscribed to the Google Groups 
"Clojure" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Guidelines/Recommendations for namespaces and qualified keywords

[Josh Tilles]

I’ve got a couple questions for Alex Miller and/or the other Cognitect 
folks.

   1. *Are single-segment namespaces still “bad” when it comes to 
   registering specs under qualified keywords?*
   In the past, single-segment namespaces have been discouraged in the 
   Clojure community—both because of Java interop concerns and because of the 
   possibility of name-collision when combining projects. However, many of the 
   spec examples I’ve seen have demonstrated registering specs under keywords 
   qualified by a single-segment namespace. For example, the guide’s 
   section on multi-spec  
   defines :search/url and :error/message. Is that because 
   namespace-qualifiers of specs shouldn’t be under the same constraints as 
   namespaces used to organize code? I’m *guessing* not; it seems more 
   likely that the single-segment namespaces have been used only to keep the 
   code snippets straightforward and focused on spec, and that “real” code 
   would alias (e.g.) my-company.my-project.search as search before 
   defining a ::search/url spec.
   
   2. *When designing, how do you decide whether to use a simple keyword or 
   a qualified one?*
   There’s an interesting mix of the two in the official docs and in the 
   code for spec itself. For example: the spec rationale 
    and guide 
    both use simple keywords 
   when labeling path components, and spec reports invocation errors for 
   instrumented functions with maps that exclusively use qualified keys at the 
   “root” but simple keywords appear as values 
   

 
   and as keys in nested maps 
   

   .

Thank you for your help. I really appreciate it.

Best,
Josh

-- 
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clojure@googlegroups.com
Note that posts from new members are moderated - please be patient with your 
first post.
To unsubscribe from this group, send email to
clojure+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
--- 
You received this message because you are subscribed to the Google Groups 
"Clojure" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.