As a counterexample to these statements consider proxy, genclass, and
it's ilk ---
I don't think reading the source is good enough to totally understand
the purpose behind those functions.
There's also the issue of providing examples in the doc string.
What's more clear,
"
Associates a value in a nested associative structure, where ks is a
sequence of keys and v is the new value and returns a new nested structure.
If any levels do not exist, hash-maps will be created.
"
---or---
"
Associates a value in a nested associative structure, where ks is a
sequence of keys and v is the new value and returns a new nested structure.
If any levels do not exist, hash-maps will be created.
Example: > (assoc-in {} [:a :B] 5)
{:a {:B 5}}
"
?
--Robert McIntyre
On Wed, Sep 8, 2010 at 3:05 AM, Sean Corfield <[email protected]> wrote:
> On Tue, Sep 7, 2010 at 11:10 PM, Mark Engelberg
> <[email protected]> wrote:
>> What pre-conditions need to be met by the inputs?
>> What invariants are maintained by the function?
>> What are the performance guarantees of the function?
>
> And this can't be expressed in a single sentence?
>
>> Many times there are dozens of functions that are interrelated. Only
>> one or two of them are the crucially important "entry points" that
>> provide the high-level API.
>
> Then reorganize your files. Each file should have a specific public API.
>
>> Good documentation makes
>> it clear what is "the right way".
>
> Fix the code. The "right way" should be the only / obvious way.
>
>> The list goes on.
>
> I just don't see these questions arising from an agile point of view...
>
>> If you want to comment your code for other
>> people to maintain it, that's even more challenging.
>
> Nonsense. That's all about good, descriptive naming. If you can't
> document your code in a single sentence, it's too complex. I keep
> hearing FP folks talking about small functions and breaking things
> down so this issue of documentation runs counter to that...
>
>> "Always code as if the guy who ends up maintaining your code will be a
>> violent psychopath who knows where you live." -- John F. Woods
>
> Most people who read my code have said it reads like poetry and they
> love it. I have almost zero comments in my code. I have literate
> function / variable names. Comments can get out of sync with code so
> the fewer comments you have, the better, as far as I'm concerned. The
> code itself should be literate.
> --
> Sean A Corfield -- (904) 302-SEAN
> Railo Technologies, Inc. -- http://getrailo.com/
> An Architect's View -- http://corfield.org/
>
> "If you're not annoying somebody, you're not really alive."
> -- Margaret Atwood
>
> --
> You received this message because you are subscribed to the Google
> Groups "Clojure" group.
> To post to this group, send email to [email protected]
> Note that posts from new members are moderated - please be patient with your
> first post.
> To unsubscribe from this group, send email to
> [email protected]
> 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 post to this group, send email to [email protected]
Note that posts from new members are moderated - please be patient with your
first post.
To unsubscribe from this group, send email to
[email protected]
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
