Google Common Lisp Style Guide

[François-René Rideau]

Dear Lispers,

I've recently taken over the editing of a document now published as the
Google Common Lisp Style Guide
http://google-styleguide.googlecode.com/svn/trunk/lispguide.xml

Maybe some of you have feedback to improve it.
The hope is, if it gets good enough, it can be useful to newbies.

—♯ƒ • François-René ÐVB Rideau •Reflection&Cybernethics• http://fare.tunes.org
Common Lisp makes it easy for you to grow your own language; however, it
makes it difficult for that language to be the same as anyone else's.

[Michael J. Forster]

On Oct 10, 2:21 pm, François-René Rideau <tu...@google.com> wrote:
> Dear Lispers,
>
> I've recently taken over the editing of a document now published as the
>    Google Common Lisp Style Guide
>    http://google-styleguide.googlecode.com/svn/trunk/lispguide.xml
>
> Maybe some of you have feedback to improve it.
> The hope is, if it gets good enough, it can be useful to newbies.

[...]

Hello François-René,

Thank you for making this available.

I've skimmed it lightly only, but here are two minor corrections in
the
"Omit library prefixes" section. Replace

...that controls the verbosity of asdf only and the entire Lisp
programs.

with

...that controls the verbosity of asdf only and not the entire
Lisp program.


Cheers,

Mike

[Pascal Costanza]

On 10/10/2012 21:21, François-René Rideau wrote:
> Dear Lispers,
>
> I've recently taken over the editing of a document now published as the
> Google Common Lisp Style Guide
> http://google-styleguide.googlecode.com/svn/trunk/lispguide.xml
>
> Maybe some of you have feedback to improve it.
> The hope is, if it gets good enough, it can be useful to newbies.

I have one to add:

"You should not add style guides that merely reflect the personal
opinions of their authors."


Pascal

--
My website: http://p-cos.net
Common Lisp Document Repository: http://cdr.eurolisp.org
Closer to MOP & ContextL: http://common-lisp.net/project/closer/
The views expressed are my own, and not those of my employer.

[Zach Beane]

Pascal Costanza <p...@p-cos.net> writes:

> On 10/10/2012 21:21, François-René Rideau wrote:
>> Dear Lispers,
>>
>> I've recently taken over the editing of a document now published as the
>> Google Common Lisp Style Guide
>> http://google-styleguide.googlecode.com/svn/trunk/lispguide.xml
>>
>> Maybe some of you have feedback to improve it.
>> The hope is, if it gets good enough, it can be useful to newbies.
>
> I have one to add:
>
> "You should not add style guides that merely reflect the personal
> opinions of their authors."

It can be somewhat difficult to faithfully reflect the personal opinions
of others.

Zach

[Barry Margolin]

In article <adov6a...@mid.individual.net>,

Pascal Costanza <p...@p-cos.net> wrote:

> On 10/10/2012 21:21, François-René Rideau wrote:
> > Dear Lispers,
> >
> > I've recently taken over the editing of a document now published as the
> > Google Common Lisp Style Guide
> > http://google-styleguide.googlecode.com/svn/trunk/lispguide.xml
> >
> > Maybe some of you have feedback to improve it.
> > The hope is, if it gets good enough, it can be useful to newbies.
>
> I have one to add:
>
> "You should not add style guides that merely reflect the personal
> opinions of their authors."

Most of it seems to be a description of traditional Lisp style that has
been the concensus for decades. Variable naming conventions,
parenthesis layout, etc.

Some parts of it look like translations of the Google C++ Style Guide to
the CL context, so I don't think those are the author's personal
opinions -- he's just maintaining consistency across different languages.

--
Barry Margolin, bar...@alum.mit.edu
Arlington, MA
*** PLEASE post questions in newsgroups, not directly to me ***

[Pascal Costanza]

On 12/10/2012 02:09, Barry Margolin wrote:
> In article <adov6a...@mid.individual.net>,
> Pascal Costanza <p...@p-cos.net> wrote:
>
>> On 10/10/2012 21:21, François-René Rideau wrote:
>>> Dear Lispers,
>>>
>>> I've recently taken over the editing of a document now published as the
>>> Google Common Lisp Style Guide
>>> http://google-styleguide.googlecode.com/svn/trunk/lispguide.xml
>>>
>>> Maybe some of you have feedback to improve it.
>>> The hope is, if it gets good enough, it can be useful to newbies.
>>
>> I have one to add:
>>
>> "You should not add style guides that merely reflect the personal
>> opinions of their authors."
>
> Most of it seems to be a description of traditional Lisp style that has
> been the concensus for decades. Variable naming conventions,
> parenthesis layout, etc.
>
> Some parts of it look like translations of the Google C++ Style Guide to
> the CL context, so I don't think those are the author's personal
> opinions -- he's just maintaining consistency across different languages.

Is there empirical evidence (not anecdotal evidence, mind you!) that
these rules buy us anything?

[Nils M Holm]

Pascal Costanza <p...@p-cos.net> wrote:
> Is there empirical evidence (not anecdotal evidence, mind you!) that
> these rules buy us anything?

If people enjoy them, it "buys" them joy.

What empirical evidence is there that using Lisp buys us anything?

--
Nils M Holm < n m h @ t 3 x . o r g > www.t3x.org

[Marco Antoniotti]

On Thursday, October 11, 2012 6:23:07 PM UTC-4, Pascal Costanza wrote:
> On 10/10/2012 21:21, François-René Rideau wrote:
>
> > Dear Lispers,
>
> >
>
> > I've recently taken over the editing of a document now published as the
>
> > Google Common Lisp Style Guide
>
> > http://google-styleguide.googlecode.com/svn/trunk/lispguide.xml
>
> >
>
> > Maybe some of you have feedback to improve it.
>
> > The hope is, if it gets good enough, it can be useful to newbies.
>
>
>
> I have one to add:
>
>
>
> "You should not add style guides that merely reflect the personal
>
> opinions of their authors."

Except mine, of course. *MY* style guides are bigger than yours! :)

Cheers
--
MA

[Antsan]

Am Mittwoch, 10. Oktober 2012 21:21:26 UTC+2 schrieb François-René Rideau:
> Dear Lispers, I've recently taken over the editing of a document now published as the Google Common Lisp Style Guide http://google-styleguide.googlecode.com/svn/trunk/lispguide.xml Maybe some of you have feedback to improve it. The hope is, if it gets good enough, it can be useful to newbies. —♯ƒ • François-René ÐVB Rideau •Reflection&Cybernethics• http://fare.tunes.org Common Lisp makes it easy for you to grow your own language; however, it makes it difficult for that language to be the same as anyone else's.

Documentation: Document Everything
I somewhere read that documentation strings very explicitely should *not* describe how code works but rather what the code does. I very strongly agree - how the code works shouldn't concern users and documentation strings are for users.

Naming: Denote intent, not content
Personally I am more comfortable with knowing what kind of data can be processed by a function. Parameter names should reflect that, I think.

Naming: Omit library prefixes:
Conflicts with your very own
Language usage guidelines: Packages

Naming: Predicate names
the -p convention is very controversial and using ? instead is very popular. The link provided doesn't explain why one shouldn't use ? or anything else instead.

Data representation: NIL: empty-list, false and I Don't Know
CL itself uses another convention for "I don't know": Provide multiple return values, the first being the found value (and a default one when none is found) and a second value that is T if there was something found and NIL when nothing was found. This seems more sensible to me then using some defined symbol that might somehow end up being actually stored in the structure you're searching in - even if it shouldn't.

Everything regarding &allow-other-keys
&allow-other-keys is useful where an &rest parameter is supposed to be a plist and no keys are actually expected.

Proper forms: Identity, Equality and Comparisons
When checking for equality of places EQ is sensible I think.

Proper forms: Iteration
Controversial topic that doesn't need to be unified in style as all kinds of iteration constructs can be used in a way that is easily readable. When unsure what to use, look for the priority list as given above.

[François-René Rideau]

>> Google Common Lisp Style Guide http://google-styleguide.googlecode.com/svn/trunk/lispguide.xml

On Friday, October 12, 2012 11:46:27 AM UTC-4, Antsan wrote:
> Documentation: Document Everything
>
> I somewhere read that documentation strings very explicitely should *not* describe how code works but rather what the code does. I very strongly agree - how the code works shouldn't concern users and documentation strings are for users.
>

You're totally right. I'll amend the wording as such:
You should use document strings to explain how to use your code.

> Naming: Denote intent, not content
>
> Personally I am more comfortable with knowing what kind of data can be processed by a function. Parameter names should reflect that, I think.
>

If your function is meant to do specifically that, that's the intent.

> Naming: Omit library prefixes:
>
> Conflicts with your very own
>
> Language usage guidelines: Packages
>

They don't actually conflict. I'll clarify the wording.

> Naming: Predicate names
>
> the -p convention is very controversial and using ? instead is very popular. The link provided doesn't explain why one shouldn't use ? or anything else instead.
>

Admittedly, it's all convention. But conventions are important.

> Data representation: NIL: empty-list, false and I Don't Know
>
> CL itself uses another convention for "I don't know": Provide multiple return values, the first being the found value (and a default one when none is found) and a second value that is T if there was something found and NIL when nothing was found. This seems more sensible to me then using some defined symbol that might somehow end up being actually stored in the structure you're searching in - even if it shouldn't.
>

Indeed. I'll add a paragraph to that effect.

> Everything regarding &allow-other-keys
>
> &allow-other-keys is useful where an &rest parameter is supposed to be a plist and no keys are actually expected.
>

Indeed. I will fix that, too.

> Proper forms: Identity, Equality and Comparisons
>
> When checking for equality of places EQ is sensible I think.
>

I'll still put that as an optimization.
It's morally the same as using EQL with a type declaration,
and should be treated equally.

> Proper forms: Iteration
>
> Controversial topic that doesn't need to be unified in style as all kinds of iteration constructs can be used in a way that is easily readable. When unsure what to use, look for the priority list as given above.
>

I don't really like this rule, but it seems to be the consensus for CL,
and makes sense for portability's sake.
Requiring users to document non-portable assumptions looks like a good bargain.

Thanks a lot for your useful feedback!

—♯ƒ • François-René ÐVB Rideau •Reflection&Cybernethics• http://fare.tunes.org

Who released the most slaves? The one who spent his wealth buying them back?
Or the capitalist who found a way to power mills with water?

[Peter]

Conditional Expressions
[...] Note that in Common Lisp, WHEN and UNLESS return NIL when the condition evaluates to NIL. [...]

(unless nil t)

T

[Pascal Costanza]

On 12/10/2012 08:58, Nils M Holm wrote:
> Pascal Costanza <p...@p-cos.net> wrote:
>> Is there empirical evidence (not anecdotal evidence, mind you!) that
>> these rules buy us anything?
>
> If people enjoy them, it "buys" them joy.
>
> What empirical evidence is there that using Lisp buys us anything?

None. That's why there is also no document that says that you "must" use
Lisp.

[Nils M Holm]

Pascal Costanza <p...@p-cos.net> wrote:
> On 12/10/2012 08:58, Nils M Holm wrote:
> > Pascal Costanza <p...@p-cos.net> wrote:
> >> Is there empirical evidence (not anecdotal evidence, mind you!) that
> >> these rules buy us anything?
> >
> > If people enjoy them, it "buys" them joy.
> >
> > What empirical evidence is there that using Lisp buys us anything?
>
> None. That's why there is also no document that says that you "must" use
> Lisp.

Nobody "must" use a style guide, either, but if it helps to avoid
grossly mal-formatted code, it is certainly an improvement.

[Pascal Costanza]

On 14/10/2012 13:58, Nils M Holm wrote:
> Pascal Costanza <p...@p-cos.net> wrote:
>> On 12/10/2012 08:58, Nils M Holm wrote:
>>> Pascal Costanza <p...@p-cos.net> wrote:
>>>> Is there empirical evidence (not anecdotal evidence, mind you!) that
>>>> these rules buy us anything?
>>>
>>> If people enjoy them, it "buys" them joy.
>>>
>>> What empirical evidence is there that using Lisp buys us anything?
>>
>> None. That's why there is also no document that says that you "must" use
>> Lisp.
>
> Nobody "must" use a style guide, either, but if it helps to avoid
> grossly mal-formatted code, it is certainly an improvement.

Did you read the document we're talking about? There are at least 24
occurrences of "must", and 32 occurrences of "should." I especially find
"You MUST follow conventions, they are not optional." somewhat hilarious...

[Nils M Holm]

Pascal Costanza <p...@p-cos.net> wrote:
> Did you read the document we're talking about? There are at least 24
> occurrences of "must", and 32 occurrences of "should." I especially find
> "You MUST follow conventions, they are not optional." somewhat hilarious...

Ah, I see. I interpret "must" in technical documents as a strong
preference and "should" as a not so strong preference.

But I agree, it sounds a bit strong in a style guide, which is
rather subjective by its very nature.

[Kaz Kylheku]

On 2012-10-12, Nils M Holm <news...@t3x.org> wrote:
> Pascal Costanza <p...@p-cos.net> wrote:
>> Is there empirical evidence (not anecdotal evidence, mind you!) that
>> these rules buy us anything?
>
> If people enjoy them, it "buys" them joy.
>
> What empirical evidence is there that using Lisp buys us anything?

Indirect only, I'm afraid.

Lisp turns you sexy, improving your personality and confidence.

This making it easier to be taken in under the auspices of a sugar mama.

[Pascal Costanza]

On 10/10/2012 21:21, François-René Rideau wrote:

- Permission and Forgiveness: Who are these code reviewers and OWNERS
[sic!] that the document talks about here? Why do they care about my
projects?

- Principles: "Every developer's code must be easy for another developer
to read, understand, and modify." Does this also apply to code that I
don't intend to release?

- "Everybody's code should look the same." I strongly object to that. An
implementation of, say, quicksort should look different from an
implementation of, say, mergesort.

- Architecture: What is being said here contradicts to some extent
principles from agile methodologies (like XP). Style guides shouldn't be
influenced by a particular development methodology, because these are
orthogonal issues.

- Using Libraries: I strongly object to the idea that people MUST NOT
[sic!] start libraries. Hobbyists can do whatever they want, and the
community should be open to hobbyists.

- Open-Sourcing Code: What if my "main project" is to modify an existing
open-source library? Do I still need to publish it separately?!? This
seems contradictory in itself...

- Everything in "development process" may be completely over the top,
depending on situation. It should not be mentioned in a style guide.

- Spelling: Seriously?!? If somebody provides useful code, and there are
minor spelling mistakes in there, is that really a problem?!?

- Line length: I'm in favor of choosing a line length of 127. [Hint:
sarcasm.]

- Indentation: LispWorks indents differently from GNU Emacs, and GNU
Emacs with SLIME indents differently than without. Some developers
(including well-known ones in the CL community) change indentation
settings to have a personal indentation style. All of that MUST (har!)
be fine for a community!

- File Header: Some of the recommendations here may conflict with
requirements of other (!) companies. A style guide shouldn't impose such
requirements.

- Vertical white space: I sometimes add two lines to distinguish between
sections of code, especially when additional comments to separate the
sections seem overkill. I don't want to discourage other hackers to use
three or four lines. Why does it even matter?!?

- Horizontal white space: I strongly object to the discouragement of
vertical alignments through horizontal spaces. This can drastically
improve readability (which supposedly was also a goal of this document).
But I also don't want to impose on others to have the same preference as
me. Such nonsense should just not be in such guidelines!

- Document everything: This is clearly wrong! Read the literature about
extreme programming for reasons why documenting everything is a really,
really bad idea!

- Comment semicolons: Somewhere in all the Common Lisp code I have
written so far, I'm pretty sure I used the wrong number of semicolons
occasionally. Am I now a bad boy?

- Naming: Many of the things mentioned here are standard practice. But
again, too many "musts" and "shoulds." This is not necessary. Just
explain what the common practice is.

- Language usage guidelines: All the subsections in here are highly
controversial. Common Lisp is a language which encourages development of
a personal coding style. A document like this should not try to restrict
this freedom. Especially controversial are: avoidance of recursion,
using special variables sparingly, avoidance of slot-value and
with-slots, all the talk about protocols, requiring that specializing
classes should inherit from the same base class (wtf!?!), not using MOP
intercession (wtf?!?). (How generous of you that you "allow" exceptions
to the rules in the document. A style guide intended for the community
should not pretend that it is a binding authority!!!)

I'll stop here. I guess you got the idea by now...

[François-René Rideau]

Oops. Poor wording indeed. What about the following?

<code>WHEN</code> and <code>UNLESS</code> return <code>NIL</code>
when the condition is not met.
You may take advantage of it.

Did you ever find a taker for your giant Lisp Machine?

—♯ƒ • François-René ÐVB Rideau •Reflection&Cybernethics• http://fare.tunes.org

I once argued that slavery was once a great progress... over anthropophagy.
Well, anthropophagy once was a great progress... over starvation.

[Paul Wallich]

On 10/14/12 5:21 PM, Pascal Costanza wrote:
> On 10/10/2012 21:21, François-René Rideau wrote:
>> Dear Lispers,
>>
>> I've recently taken over the editing of a document now published as the
>> Google Common Lisp Style Guide
>> http://google-styleguide.googlecode.com/svn/trunk/lispguide.xml
>>
>> Maybe some of you have feedback to improve it.
>> The hope is, if it gets good enough, it can be useful to newbies.
>>
>> —♯ƒ • François-René ÐVB Rideau •Reflection&Cybernethics•
>> http://fare.tunes.org
>> Common Lisp makes it easy for you to grow your own language; however, it
>> makes it difficult for that language to be the same as anyone else's.
>
> - Permission and Forgiveness: Who are these code reviewers and OWNERS
> [sic!] that the document talks about here? Why do they care about my
> projects?
>
> - Principles: "Every developer's code must be easy for another developer
> to read, understand, and modify." Does this also apply to code that I
> don't intend to release?

Absolutely. Because you, six months or a year or five years from now,
almost certainly qualify as "another developer". If you write (and
sparsely document) something in a fashion that can only be understood by
you at the moment of maximum understanding that goes with being in the
middle of writing a particular piece of complex code, the older version
of you will regret it.

paul

[Barry Margolin]

In article <ae0auo...@mid.individual.net>,

Nils M Holm <news...@t3x.org> wrote:

Using the style guide in the first place is merely a SHOULD. So the
qualifiers within it should be understood in that context.

[Barry Margolin]

In article <ae0omr...@mid.individual.net>,
Pascal Costanza <p...@p-cos.net> wrote:

> On 10/10/2012 21:21, Fran ois-RenŽ Rideau wrote:
> > Dear Lispers,
> >
> > I've recently taken over the editing of a document now published as the
> > Google Common Lisp Style Guide
> > http://google-styleguide.googlecode.com/svn/trunk/lispguide.xml
> >
> > Maybe some of you have feedback to improve it.
> > The hope is, if it gets good enough, it can be useful to newbies.
> >

> > �織 � Fran ois-RenŽ ÐVB Rideau •Reflection&Cybernethics•

> > http://fare.tunes.org
> > Common Lisp makes it easy for you to grow your own language; however, it
> > makes it difficult for that language to be the same as anyone else's.
>
> - Permission and Forgiveness: Who are these code reviewers and OWNERS
> [sic!] that the document talks about here? Why do they care about my
> projects?

If that's your attitude, why do you care about the style guide at all?

I think Google's style guides are aimed at authors of open source
projects will be posted to code.google.com.

[François-René Rideau]

Dear Pascal,

>> Google Common Lisp Style Guide
>> http://google-styleguide.googlecode.com/svn/trunk/lispguide.xml

> - Permission and Forgiveness: Who are these code reviewers and OWNERS
> [sic!] that the document talks about here? Why do they care about my
> projects?
>

I don't see what you're getting so upset about:
No one really cares about your projects.

If call them "my projects", you are tautologically the owner of them, and
you get to choose who reviews your code (if anyone will) and
who else's code to review (if anyone contributes).

Just like the other Google Style Guides, this document
only claims to apply to code written at Google.
Google will NOT be sending SWAT teams to take out
non-Google hackers who fail to abide by the recommendations,
nor to abduct them and lock them into FEMA camps.
There isn't even any expected sanction against Google hackers
who fail to abide by the recommendations, beside remarks
from their reviewers or subsequent passes that fix their code.

We publish these Guides both as a service to the general community,
with the hope that they may be of some help to developers
(newbies especially so),
and as a way for us to gather feedback
(of which we've got plenty).

(As an aside, I interrupt this flamewar to profusively thank
to all those who replied with constructive comments;
I may not be replying to all of you individually,
but I'll continue integrating all your remarks.)

> - Principles: "Every developer's code must be easy for another developer
> to read, understand, and modify." Does this also apply to code that I
> don't intend to release?
>

Of course. God is watching you, and every time you fail him, a puppy dies.

As for me, I often find that I'm a different developer from the one I used
to be a few years back when I wrote a piece of code, and I'm grateful to
that other developer when he made his code readable, and less grateful
when he didn't.

> - "Everybody's code should look the same." I strongly object to that.
> An implementation of, say, quicksort should look different from an
> implementation of, say, mergesort.
>

I don't see how that's relevant to who writes the code.
Hopefully, Steve's quicksort will be similar enough to Scott's quicksort,
and Ben's mergesort will be similar enough to David's mergesort.
Whether to use quicksort or mergesort
(and whether to bother implementing yet another sort)
should be decided based on technical considerations.

> - Architecture: What is being said here contradicts to some extent
> principles from agile methodologies (like XP). Style guides shouldn't be
> influenced by a particular development methodology, because these are
> orthogonal issues.
>

Any drone strike against hackers who dare to follow methodologies
that differ from Google is purely coincidental.
Please disregard any children dying as collateral damage.

> - Using Libraries: I strongly object to the idea that people MUST NOT
> [sic!] start libraries. Hobbyists can do whatever they want, and the
> community should be open to hobbyists.
>

Oh noes! More puppies dying.

> - Open-Sourcing Code: What if my "main project" is to modify an existing
> open-source library? Do I still need to publish it separately?!? This
> seems contradictory in itself...
>

My head has exploded already.
The rest of this message is provided courtesy of Emacs auto-reply-mode.

> - Everything in "development process" may be completely over the top,
> depending on situation. It should not be mentioned in a style guide.
>

Sir, yes sir.

> - Spelling: Seriously?!? If somebody provides useful code, and there are
> minor spelling mistakes in there, is that really a problem?!?
>

Speling misstakes ain't no problem z'long as
the very same mistayke iz made consistently by evrywun.

> - Line length: I'm in favor of choosing a line length of 127. [Hint:
> sarcasm.]
>

Of course. Google will immediately amend its policies.

> - Indentation: LispWorks indents differently from GNU Emacs, and GNU
> Emacs with SLIME indents differently than without. Some developers
> (including well-known ones in the CL community) change indentation
> settings to have a personal indentation style. All of that MUST (har!)
> be fine for a community!
>

If and when any of them comes contribute code to one of our projects,
they will use the same settings as we do,
thanks to the configuration files we provide.

> - File Header: Some of the recommendations here may conflict with
> requirements of other (!) companies. A style guide shouldn't impose such
> requirements.
>

Soon enough, Google will buy those companies and reformat their code.
Unless droning is cheaper.

> - Vertical white space: I sometimes add two lines to distinguish between
> sections of code, especially when additional comments to separate the
> sections seem overkill. I don't want to discourage other hackers to use
> three or four lines. Why does it even matter?!?
>

If it doesn't matter, why be so upset about it?

> - Horizontal white space: I strongly object to the discouragement of
> vertical alignments through horizontal spaces. This can drastically
> improve readability (which supposedly was also a goal of this document).
> But I also don't want to impose on others to have the same preference as
> me. Such nonsense should just not be in such guidelines!
>

There are reasons to align things vertically.
Absent such reasons, it is only distracting to align vertically,
which only suggests a reason that doesn't exist.
By following such conventions, it becomes easier to convey meaning.

> - Document everything: This is clearly wrong! Read the literature about
> extreme programming for reasons why documenting everything is a really,
> really bad idea!
>

There are good reasons to document things in a project
with tens of other people who will have to maintain your code
long after you're gone.

This rule obviously does not apply to throwaway code,
code written by immortals who never quit,
and code written by people who are going to be droned imminently, anyway.

> - Comment semicolons: Somewhere in all the Common Lisp code I have
> written so far, I'm pretty sure I used the wrong number of semicolons
> occasionally. Am I now a bad boy?
>

You are very naughty body indeed, Mr Costanza.
I don't think Santa will come visit you this year.

> - Naming: Many of the things mentioned here are standard practice. But
> again, too many "musts" and "shoulds." This is not necessary. Just
> explain what the common practice is.
>

MUSTs and SHOULDs are indeed descriptive of common practice.
Some constraints are stronger than others, and it is appropriate
to use different words to express this difference in strength.

> - Language usage guidelines: All the subsections in here are highly
> controversial. Common Lisp is a language which encourages development of
> a personal coding style. A document like this should not try to restrict
> this freedom. Especially controversial are: avoidance of recursion,
> using special variables sparingly, avoidance of slot-value and
> with-slots, all the talk about protocols, requiring that specializing
> classes should inherit from the same base class (wtf!?!), not using MOP
> intercession (wtf?!?). (How generous of you that you "allow" exceptions
> to the rules in the document. A style guide intended for the community
> should not pretend that it is a binding authority!!!)
>

The entire purpose of a Style Guide is make it easier for many developers
to communicate with each other by laying down common expectations as to
what code looks like by default, thereby allowing developers to raise
awareness when they challenge those defaults. If there are no defaults,
then discrepancies are just costly noise that readers must ignore,
rather than beneficial signals that they must pay attention to.

Now at long last, I find some technical content to your message.
I'll clarify the rationale.

Regarding special variables, they are state,
introduce complexity due to potential interaction,
are costly to manage, and should only be used
when their benefits are greater than these costs.
I will add a paragraph to that effect.

Slot-values are low-level. Most of the time, you should be
on the other side of the abstraction barrier. Use accessors.

Yes, base classes are cleaner.
They are a locus for documentation, specialization, etc.
You can't retrofit them onto other people's code.
You can and should add them to your own.

Regarding not using MOP intercession,
I didn't write this guideline, but I'll stand by it.
At runtime, they are at worst a danger, at best a performance issue.
At compile-time, it is cleaner that
macros should things up the right way on the first pass,
without the need to modify things in a second pass.
They are great tools for interactive development and IDE,
but you should not use them in the code being developed.

You are the only one here who suggests
the guide is intended for "the" community.
I was not aware there was One and only One community,
and that YOU were its spokesperson. My apologies.

> I'll stop here. I guess you got the idea by now...
>

I get that you are confused as to the intended purpose of this Guide.

—♯ƒ • François-René ÐVB Rideau •Reflection&Cybernethics• http://fare.tunes.org

To avoid criticism, do nothing, say nothing, and be nothing. – Elbert Hubbard

[Nils M Holm]

Of course! How could I forget about that!

[Nicolas Neuss]

Thank you, Pascal, for taking the time for writing this post. I have
mostly the same feelings with respect to this style guide.

Of course, everyone has the freedom to post whatever style
recommendations he wants, but vice versa I allow myself the freedom to
consider this style guide as "not really helpful" (for anyone). This is
in strong contrast to the Norvig/Pitman style guide, which I find very
good and useful.

Nicolas

[Michael Filonenko]

Thanks.

May I translate it?

[Faré]

On Monday, October 15, 2012 8:25:02 AM UTC-4, Michael Filonenko wrote:
> May I translate it?

But of course you may, and I'll be honored.
Please would make sure to write down and advertise
which revision of the text you base your translation from,
so you can translate the diffs.
I already have more fixes based on remarks made in here, at Google, etc.
I appreciate it if you send me the URL by personal email when you're done.

—♯ƒ • François-René ÐVB Rideau •Reflection&Cybernethics• http://fare.tunes.org

The real danger is that one day machines *will* become intelligent,
but we'll lack the mental equipment to notice.
— Tiresias, in J.-P. Petit, "Run, Robot, Run"

[Raymond Wiker]

Nicolas Neuss <last...@scipolis.de> writes:

> Thank you, Pascal, for taking the time for writing this post. I have
> mostly the same feelings with respect to this style guide.
>
> Of course, everyone has the freedom to post whatever style
> recommendations he wants, but vice versa I allow myself the freedom to
> consider this style guide as "not really helpful" (for anyone). This is
> in strong contrast to the Norvig/Pitman style guide, which I find very
> good and useful.

It should perhaps be noted that Google is a company that can
afford to employ *several* Lisp programmers, who are actually allowed to
code in Lisp at work. That is a different situation to most Lisp
programmers, I guess...

[Nicolas Neuss]

:-) OK, this is a good point.

Nicolas

[François-René Rideau]

>> Nicolas Neuss writes:
>>> Of course, everyone has the freedom to post whatever style
>>> recommendations he wants, but vice versa I allow myself the freedom to
>>> consider this style guide as "not really helpful" (for anyone). This is
>>> in strong contrast to the Norvig/Pitman style guide, which I find very
>>> good and useful.

> Raymond Wiker writes:
>> It should perhaps be noted that Google is a company that can
>> afford to employ *several* Lisp programmers, who are actually allowed to
>> code in Lisp at work. That is a different situation to most Lisp
>> programmers, I guess...

Nicolas Neuss writes:
> :-) OK, this is a good point.

I amended the introduction to the Guide,
in a probably vain attempt to dispel confusion as to its purpose.

Yes, the entire purpose of the Guide is to help Lisp hackers at Google
work together rather than enter commit wars or endless arguments,
to give us common rules to settle disputes about style, and
to make it easier for us to read and modify each other's code.

We make no claim whatsoever to control how people outside Google
write code that is not part of our code base.
We just hope our guides provide food for thought,
and that in return some of you provide useful feedback
— which you do, and for which I personally thank you.

I hope you will find the current version of the guide more satisfying
(1.13 as I'm writing these lines).
I will keep updating the guide as I get useful objections and suggestions.

NB: Once again, it is a purely coincidental tragedy
if any of Google's self-driving cars ever runs over
any hacker who dared to challenge our style guides in any of his own code.
We deny any rumor that we are actually working
for the Borg to take over the world.
And we are not giving any government entity any information about any of you
based on any subpoena with an accompanying gag order, so far as we can tell.

—♯ƒ • François-René ÐVB Rideau •Reflection&Cybernethics• http://fare.tunes.org

One can be so anxious to put his "best foot forward" that he doesn't even
notice that it isn't his own foot. — Harry Browne (HIFFIAUW)

[Pascal Costanza]

On 15/10/2012 06:03, François-René Rideau wrote:

> Regarding special variables, they are state,
> introduce complexity due to potential interaction,
> are costly to manage, and should only be used
> when their benefits are greater than these costs.
> I will add a paragraph to that effect.

Special variables can greatly enhance modularization of software. Please
study "The Art of the Interpreter" where this is convincingly argued
(IMHO). See
http://repository.readscheme.org/ftp/papers/ai-lab-pubs/AIM-453.pdf

That language constructs should be used only if their benefits are
greater than their costs is a trivial truth, and applies to any language
construct. It's unclear why this should apply "more" to special
variables than to other constructs. Maybe what you want to say is that
for special variables, this is less often the case than with other
constructs. But even that statement is fuzzy at best...

> Slot-values are low-level. Most of the time, you should be
> on the other side of the abstraction barrier. Use accessors.

This is generally true, but not always. Not, also, that you have
stronger ways of enforcing that additional behavior is triggered by
using the MOP.

> Yes, base classes are cleaner.
> They are a locus for documentation, specialization, etc.
> You can't retrofit them onto other people's code.
> You can and should add them to your own.

This is only true if you misunderstand CLOS. Unlike other OOP languages,
CLOS is not class-centric, but centered around generic functions. It's a
strong advantage that generic functions can be specialized on
dissociated classes and objects (and more). It's a bad idea to suggest
that CLOS should be used like other OOP languages, because that misses
the point.

> Regarding not using MOP intercession,
> I didn't write this guideline, but I'll stand by it.
> At runtime, they are at worst a danger, at best a performance issue.
> At compile-time, it is cleaner that
> macros should things up the right way on the first pass,
> without the need to modify things in a second pass.
> They are great tools for interactive development and IDE,
> but you should not use them in the code being developed.

There are concepts that are more straightforward and more elegant to
express with runtime intercession rather than compile-time intercession.
It's better to understand what these cases are, rather than have some
artificial "you shalt not do this" rules that may prevent people from
understanding the deeper issues if they just blindly follow such rules.

> You are the only one here who suggests
> the guide is intended for "the" community.
> I was not aware there was One and only One community,
> and that YOU were its spokesperson. My apologies.

I'm not the spokesperson of the community. I never claimed I am. I just
want to be sure that there is no spokesperson.

> I get that you are confused as to the intended purpose of this Guide.

Indeed, it seems so.

[Pascal Costanza]

This is a major improvement of this guide. Thank you for the clarification.

[Didier Verna]

François-René Rideau <tu...@google.com> wrote:

> We deny any rumor that we are actually working for the Borg to take
> over the world.

Resistance is futile !!

--
Resistance is futile. You will be jazzimilated.

Scientific site: http://www.lrde.epita.fr/~didier
Music (Jazz) site: http://www.didierverna.com

[Marco Antoniotti]

On Tuesday, October 16, 2012 8:24:36 AM UTC-4, Didier Verna wrote:
> François-René Rideau <tu...@google.com> wrote:
>
>
>
> > We deny any rumor that we are actually working for the Borg to take
>
> > over the world.
>
>
>
> Resistance is futile !!
>

That depends on whether you can see octarine or not :)

Cheers
--
MA

[Barry Margolin]

In article <ae4edp...@mid.individual.net>,

Pascal Costanza <p...@p-cos.net> wrote:

> On 15/10/2012 06:03, François-René Rideau wrote:
> > Slot-values are low-level. Most of the time, you should be
> > on the other side of the abstraction barrier. Use accessors.
>
> This is generally true, but not always.

Isn't that what "most of the time" means?

[Pascal Costanza]

On 16/10/2012 16:32, Barry Margolin wrote:
> In article <ae4edp...@mid.individual.net>,
> Pascal Costanza <p...@p-cos.net> wrote:
>
>> On 15/10/2012 06:03, François-René Rideau wrote:
>>> Slot-values are low-level. Most of the time, you should be
>>> on the other side of the abstraction barrier. Use accessors.
>>
>> This is generally true, but not always.
>
> Isn't that what "most of the time" means?

There are situations where most of the time, using slot-value is the
right side of the abstraction barrier.

[Barry Margolin]

In article <ae5up7...@mid.individual.net>,

Pascal Costanza <p...@p-cos.net> wrote:

> On 16/10/2012 16:32, Barry Margolin wrote:
> > In article <ae4edp...@mid.individual.net>,
> > Pascal Costanza <p...@p-cos.net> wrote:
> >
> >> On 15/10/2012 06:03, François-René Rideau wrote:
> >>> Slot-values are low-level. Most of the time, you should be
> >>> on the other side of the abstraction barrier. Use accessors.
> >>
> >> This is generally true, but not always.
> >
> > Isn't that what "most of the time" means?
>
> There are situations where most of the time, using slot-value is the
> right side of the abstraction barrier.

But those situations don't come up most of the time.