Blame - lispguide.xml - platform/external/google-styleguide

blob: 519e1a0baab9d1a3ee43dbb56792c25e213a31f1 [file] [log] [blame]

tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	1	<?xml version="1.0"?>
tunes@google.com	8dba399	2012-10-10 19:10:55 +0000	[diff] [blame]	2	<?xml-stylesheet type="text/xsl" href="styleguide.xsl"?>
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	3	<GUIDE title="Google Common Lisp Style Guide">
				4
tunes@google.com	0c584cb	2012-10-11 17:06:57 +0000	[diff] [blame]	5
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	6	<p align="right">
				7
tunes@google.com	cf1841c	2014-03-18 00:14:41 +0000	[diff] [blame]	8	Revision 1.28
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	9	</p>
				10
				11
				12	<address>
				13	Robert Brown
				14	</address>
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	15	<address>
mark@chromium.org	8190c13	2013-03-21 16:03:26 +0000	[diff] [blame]	16	<a HREF="mailto:tunes@google.com">François-René Rideau</a>
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	17	</address>
				18
				19	<address>
				20	In memoriam Dan Weinreb
				21	</address>
				22
tunes@google.com	8c4c5ce	2012-10-12 23:16:43 +0000	[diff] [blame]	23	<p align="center">
mark@chromium.org	8190c13	2013-03-21 16:03:26 +0000	[diff] [blame]	24	<cite>Patterns mean "I have run out of language."</cite> — Rich Hickey
tunes@google.com	8c4c5ce	2012-10-12 23:16:43 +0000	[diff] [blame]	25	</p>
				26
				27
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	28	<OVERVIEW>
				29	<CATEGORY title="Important Note">
				30	<STYLEPOINT title="Note: Displaying Hidden Details in this Guide">
				31	<SUMMARY>
				32	This style guide contains many details
				33	that are initially hidden from view.
				34	They are marked by the triangle icon, which you see here on your left.
				35	Click it now. You should see "Hooray" appear below.
				36	</SUMMARY>
				37	<BODY>
				38	<p>
				39	Hooray! Now you know you can expand points to get more details.
				40	Alternatively, there's an "expand all" at the top of this document.
				41	</p>
				42	</BODY>
				43	</STYLEPOINT>
				44	</CATEGORY>
				45	<CATEGORY title="Background">
				46	<p>
				47	Common Lisp is a powerful multiparadigm programming language.
				48	With great power comes great responsibility.
tunes@google.com	13bb6e4	2012-10-15 20:57:01 +0000	[diff] [blame]	49	</p>
				50	<p>
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	51	This guide recommends formatting and stylistic choices
				52	designed to make your code easier for other people to understand.
tunes@google.com	1407ba7	2012-11-08 04:31:59 +0000	[diff] [blame]	53	For those internal applications and free software libraries that
				54	we develop at Google,
				55	you should keep within these guidelines when making changes.
				56	Note however that each project has its own rules and customs
				57	that complement or override these general guidelines;
				58	the speed-oriented QPX low fare search engine notably
				59	has a very different style and feel from the QRes reservation system.
tunes@google.com	13bb6e4	2012-10-15 20:57:01 +0000	[diff] [blame]	60	</p>
				61	<p>
				62	If you're writing Common Lisp code outside Google,
tunes@google.com	1407ba7	2012-11-08 04:31:59 +0000	[diff] [blame]	63	we invite you to consider these guidelines.
				64	You may find some of them useful
				65	where they don't conflict with other priorities you have.
				66	We welcome remarks and constructive feedback
				67	on how to improve our guide, and
				68	on what alternate styles work for you and why.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	69	</p>
				70
				71	<p>
				72	This guide is not a Common Lisp tutorial.
				73	For basic information about the language, please consult
				74	<a HREF="http://www.gigamonkeys.com/book/">Practical Common Lisp</a>.
				75	For a language reference, please consult the
				76	<a HREF="http://www.lispworks.com/documentation/HyperSpec/Front/index.htm">Common Lisp HyperSpec</a>.
mark@chromium.org	7b24563	2013-09-25 21:16:00 +0000	[diff] [blame]	77	For more detailed style guidance, take (with a pinch of salt)
				78	a look at Peter Norvig and Kent Pitman's
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	79	<a HREF="http://norvig.com/luv-slides.ps">style guide</a>.
				80	</p>
				81	</CATEGORY>
				82	</OVERVIEW>
				83	<CATEGORY title="Meta-Guide">
				84	<STYLEPOINT title="Must, Should, May, or Not">
				85	<SUMMARY>
				86	Each guideline's level of importance is indicated
				87	by use of the following keywords and phrases, adapted from
Ackermann Yuriy	7969290	2016-04-01 21:41:34 +1300	[diff] [blame]	88	<a href="https://www.ietf.org/rfc/rfc2119.txt">RFC 2119</a>.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	89	</SUMMARY>
				90	<BODY>
				91	<table>
				92	<tr>
				93	<th valign="top">MUST</th>
				94	<td>
				95	<p>
				96	This word, or the terms "REQUIRED" or "SHALL",
				97	means that the guideline is an absolute requirement.
				98	You must ask permission to violate a MUST.
				99	</p>
				100	</td>
				101	</tr>
				102	<tr>
				103	<th valign="top">MUST NOT</th>
				104	<td>
				105	<p>
				106	This phrase, or the phrase "SHALL NOT",
				107	means that the guideline is an absolute prohibition.
				108	You must ask permission to violate a MUST NOT.
				109	</p>
				110	</td>
				111	</tr>
				112	<tr>
				113	<th valign="top">SHOULD</th>
				114	<td>
				115	<p>
				116	This word, or the adjective "RECOMMENDED", means that
				117	there may exist valid reasons in particular circumstances
				118	to ignore the demands of the guideline, but
				119	the full implications must be understood and carefully weighed
				120	before choosing a different course.
				121	You must ask forgiveness for violating a SHOULD.
				122	</p>
				123	</td>
				124	</tr>
				125	<tr>
				126	<th valign="top">SHOULD NOT</th>
				127	<td>
				128	<p>
				129	This phrase, or the phrase "NOT RECOMMENDED", means that
				130	there may exist valid reasons in particular circumstances
				131	to ignore the prohibitions of this guideline, but
				132	the full implications should be understood and carefully weighed
				133	before choosing a different course.
				134	You must ask forgiveness for violating a SHOULD NOT.
				135	</p>
				136	</td>
				137	</tr>
				138	<tr>
				139	<th valign="top">MAY</th>
				140	<td>
				141	<p>
				142	This word, or the adjective "OPTIONAL",
				143	means that an item is truly optional.
				144	</p>
				145	</td>
				146	</tr>
				147	</table>
				148	<p>
				149	Unlike RFCs, we don't capitalize every instance of one of the above
				150	keywords when it is used.
				151	</p>
				152	</BODY>
				153	</STYLEPOINT>
				154	<STYLEPOINT title="Permission and Forgiveness">
				155	<SUMMARY>
				156	There are cases where transgression of some of these rules
				157	is useful or even necessary.
				158	In some cases, you must seek permission or obtain forgiveness
				159	from the proper people.
				160	</SUMMARY>
				161	<BODY>
				162	<p>
tunes@google.com	13bb6e4	2012-10-15 20:57:01 +0000	[diff] [blame]	163	Permission comes from the owners of your project.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	164	</p>
tunes@google.com	13bb6e4	2012-10-15 20:57:01 +0000	[diff] [blame]	165
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	166	<p>
				167	Forgiveness is requested in a comment
				168	near the point of guideline violation,
				169	and is granted by your code reviewer.
				170	The original comment should be signed by you, and
				171	the reviewer should add a signed approval to the comment at review time.
				172	</p>
				173
				174	</BODY>
				175	</STYLEPOINT>
				176	<STYLEPOINT title="Conventions">
				177	<SUMMARY>
tunes@google.com	8c4c5ce	2012-10-12 23:16:43 +0000	[diff] [blame]	178	You MUST follow conventions. They are not optional.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	179	</SUMMARY>
tunes@google.com	8c4c5ce	2012-10-12 23:16:43 +0000	[diff] [blame]	180	<BODY>
				181	<p>
				182	Some of these guidelines are motivated by universal principles of good programming.
				183	Some guidelines are motivated by technical peculiarities of Common Lisp.
tunes@google.com	d6c053f	2013-09-19 17:26:22 +0000	[diff] [blame]	184	Some guidelines were once motivated by a technical reason,
tunes@google.com	8c4c5ce	2012-10-12 23:16:43 +0000	[diff] [blame]	185	but the guideline remained after the reason subsided.
				186	Some guidelines, such those about as comments and indentation,
				187	are based purely on convention, rather than on clear technical merit.
				188	Whatever the case may be, you must still follow these guidelines,
				189	as well as other conventional guidelines
				190	that have not been formalized in this document.
tunes@google.com	13bb6e4	2012-10-15 20:57:01 +0000	[diff] [blame]	191	</p>
				192	<p>
				193	You MUST follow conventions.
				194	They are important for readability.
				195	When conventions are followed by default,
				196	violations of the convention are a signal
				197	that something notable is happening and deserves attention.
				198	When conventions are systematically violated,
				199	violations of the convention are a distracting noise
				200	that needs to be ignored.
tunes@google.com	8c4c5ce	2012-10-12 23:16:43 +0000	[diff] [blame]	201	</p>
				202	<p>
				203	Conventional guidelines <em>are</em> indoctrination.
				204	Their purpose is to make you follow the mores of the community,
				205
				206	so you can more effectively cooperate with existing members.
				207	It is still useful to distinguish the parts that are technically motivated
				208	from the parts that are mere conventions,
				209	so you know when best to defy conventions for good effect,
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	210	and when not to fall into the pitfalls that the conventions are there to help avoid.
tunes@google.com	8c4c5ce	2012-10-12 23:16:43 +0000	[diff] [blame]	211	</p>
				212	</BODY>
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	213	</STYLEPOINT>
				214	<STYLEPOINT title="Old Code">
tunes@google.com	d6c053f	2013-09-19 17:26:22 +0000	[diff] [blame]	215	<SUMMARY>
				216	Fix old code as you go.
				217	</SUMMARY>
				218	<BODY>
				219	<p>
				220	A lot of our code was written before these guidelines existed.
				221	You should fix violations as you encounter them
				222	in the course of your normal coding.
				223	</p>
				224	<p>
				225	You must not fix violations en masse
				226	without warning other developers and coordinating with them,
				227	so as not to make the merging of large branches
				228	more difficult than it already is.
				229	</p>
				230	</BODY>
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	231	</STYLEPOINT>
				232	<STYLEPOINT title="Future Topics">
				233	<SUMMARY>
				234	There are many topics for additional standardization
				235	not covered by current version of this document,
				236	but deferred to future versions.
				237	</SUMMARY>
				238	<BODY>
				239	<ul>
				240	<li>
				241	File and directory structure
				242	</li>
				243	<li>
				244	Packages and modularity
				245	</li>
				246	<li>
				247	Threads and locking
				248	</li>
				249	<li>
				250	How to add configurable components
				251	</li>
				252	<li>
				253	CLOS style: initforms, slot and accessor names, etc.
				254	</li>
				255	<li>
				256	Recommendations on max number of slots per class.
				257	</li>
				258	<li>
				259	More concrete examples of good code:
				260	<ul>
				261	<li>
				262	exceptions
				263	</li>
				264	<li>
				265	transactions, with retry
				266	</li>
				267	<li>
				268	XML
				269	</li>
				270	<li>
				271	typing
				272	</li>
				273	<li>
				274	encapsulation / abstraction
				275	</li>
				276	<li>
				277	class and slot names
				278	</li>
				279	<li>
				280	etc.
				281	</li>
				282	</ul>
				283	</li>
				284	<li>
				285	When (not) to use conditional compilation:
				286	<ul>
				287	<li>
				288	modifying the product
				289	</li>
				290	<li>
				291	conditional debugging/console output/etc.
				292	</li>
				293	<li>
				294	"temporarily" commenting-out blocks of code
				295	</li>
				296	<li>
				297	etc.
				298	</li>
				299	</ul>
				300	</li>
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	301	</ul>
				302	</BODY>
				303	</STYLEPOINT>
				304	</CATEGORY>
				305	<CATEGORY title="General Guidelines">
				306	<STYLEPOINT title="Principles">
				307	<SUMMARY>
				308	There are some basic principles for team software development
				309	that every developer must keep in mind.
				310	Whenever the detailed guidelines are inadequate, confusing or contradictory,
				311	refer back to these principles for guidance:
				312	<ul>
				313	<li>
				314	Every developer's code must be easy for another developer
				315	to read, understand, and modify
mark@chromium.org	8190c13	2013-03-21 16:03:26 +0000	[diff] [blame]	316	— even if the first developer isn't around to explain it.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	317	(This is the "hit by a truck" principle.)
				318	</li>
				319	<li>
				320	Everybody's code should look the same.
				321	Ideally, there should be no way to look at lines of code
				322	and recognize it as "Fred's code" by its style.
				323	</li>
				324	<li>
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	325	Be precise.
				326	</li>
				327	<li>
				328	Be concise.
				329	</li>
				330	<li>
mark@chromium.org	8190c13	2013-03-21 16:03:26 +0000	[diff] [blame]	331	KISS — Keep It Simple, Stupid.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	332	</li>
				333	<li>
				334	Use the smallest hammer for the job.
				335	</li>
				336	<li>
				337	Use common sense.
				338	</li>
				339	<li>
				340	Keep related code together.
				341	Minimize the amount of jumping around
				342	someone has to do to understand an area of code.
				343	</li>
				344	</ul>
				345	</SUMMARY>
				346	<BODY>
				347	</BODY>
				348	</STYLEPOINT>
				349	<STYLEPOINT title="Priorities">
				350	<SUMMARY>
				351	<p>
				352	When making decisions about how to write a given piece of
				353	code, aim for the following -ilities in this priority order:
				354	</p>
				355	<ul>
				356	<li>
				357	Usability by the customer
				358	</li>
				359	<li>
				360	Debuggability/Testability
				361	</li>
				362	<li>
				363	Readability/Comprehensibility
				364	</li>
				365	<li>
				366	Extensibility/Modifiability
				367	</li>
				368	<li>
				369	Efficiency (of the Lisp code at runtime)
				370	</li>
				371	</ul>
				372	</SUMMARY>
				373	<BODY>
				374	<p>
				375	Most of these are obvious.
				376	</p>
				377	<p>
				378	Usability by the customer means that the system has to do what the
				379	customer requires; it has to handle the customer's transaction
				380	volumes, uptime requirements; etc.
				381	</p>
				382	<p>
				383	For the Lisp efficiency point,
				384	given two options of equivalent complexity,
				385	pick the one that performs better.
				386	(This is often the same as the one that conses less,
				387	i.e. allocates less storage from the heap.)
				388	</p>
				389	<p>
				390	Given two options where one is more complex than the other,
				391	pick the simpler option and revisit the decision only if
				392	profiling shows it to be a performance bottleneck.
				393	</p>
				394	<p>
				395	However, avoid premature optimization.
				396	Don't add complexity to speed up something that runs rarely,
				397	since in the long run, it matters less whether such code is fast.
				398	</p>
				399	</BODY>
				400	</STYLEPOINT>
				401	<STYLEPOINT title="Architecture">
				402	<SUMMARY>
				403	To build code that is robust and maintainable,
				404	it matters a lot how the code is divided into components,
				405	how these components communicate,
				406	how changes propagate as they evolve,
				407	and more importantly
				408	how the programmers who develop these components communicate
				409	as these components evolve.
				410	</SUMMARY>
				411	<BODY>
				412	<p>
				413	If your work affects other groups, might be reusable across groups,
				414	adds new components, has an impact on other groups
				415	(including QA or Ops), or otherwise isn't purely local,
				416	you must write it up using at least a couple of paragraphs,
				417	and get a design approval from the other parties involved
mark@chromium.org	8190c13	2013-03-21 16:03:26 +0000	[diff] [blame]	418	before starting to write code — or be ready to scratch what you have
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	419	when they object.
				420	</p>
				421	<p>
				422	If you don't know or don't care about these issues,
				423	ask someone who does.
				424	</p>
				425	</BODY>
				426	</STYLEPOINT>
				427	<STYLEPOINT title="Using Libraries">
				428	<SUMMARY>
				429	Often, the smallest hammer is to use an existing library.
				430	Or one that doesn't exist yet.
				431	In such cases, you are encouraged to use or develop such a library,
				432	but you must take appropriate precautions.
				433	</SUMMARY>
				434	<BODY>
				435	<ul>
				436	<li>
				437	You MUST NOT start a new library
				438	unless you established that none is already available
				439	that can be fixed or completed into becoming what you need.
				440	That's a rule against the NIH syndrome ("Not Invented Here"),
				441	which is particularly strong amongst Lisp hackers.
				442	</li>
				443	<li>
				444	Whichever library, old or new, you pick, you MUST get permission
				445	to incorporate third-party code into the code base.
				446	You must discuss the use of such library
				447	in the appropriate mailing-list,
				448	and have your code reviewed by people knowledgeable in the domain
				449	and/or the Lisp library ecosystem (if any).
				450	Please be ready to argue why this particular solution makes sense
				451	as compared to other available libraries.
				452	</li>
				453	<li>
				454	Some libraries are distributed under licenses not compatible
				455	with the software you're writing, and
				456	must not be considered available for use.
				457	Be aware of these issues, or consult with people who are.
				458	</li>
				459	</ul>
				460
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	461	</BODY>
				462	</STYLEPOINT>
				463	<STYLEPOINT title="Open-Sourcing Code">
				464	<SUMMARY>
				465	<p>
				466	If you write a general-purpose library,
				467	or modify an existing open-source library,
				468	you are encouraged to publish the result
				469	separate from your main project and then
				470	have your project import it like any other open-source library.
				471	</p>
				472
				473	</SUMMARY>
				474	<BODY>
				475	<p>
tunes@google.com	13bb6e4	2012-10-15 20:57:01 +0000	[diff] [blame]	476	Use your judgment to distinguish
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	477	general-purpose versus business-specific code,
				478	and open-source the general-purpose parts,
				479	while keeping the business-specific parts a trade secret.
				480	</p>
				481
				482	<p>
				483	Open-Sourcing code has many advantages,
				484	including being able to leverage third parties for development,
				485	letting the development of features be user-directed,
				486	and keeping you honest with respect to code quality.
				487	Whatever code you write, you will have to maintain anyway,
				488	and make sure its quality is high enough to sustain use in production.
				489	There should therefore be no additional burden to Open-Sourcing,
				490	even of code that (at least initially)
				491	is not directly usable by third parties.
				492	</p>
				493
				494	</BODY>
				495	</STYLEPOINT>
				496	<STYLEPOINT title="Development Process">
				497	<SUMMARY>
				498	Development process is outside the scope of this document.
				499	However, developers should remember at least these bits:
				500	get reviewed, write tests, eliminate warnings, run tests, avoid mass-changes.
				501	</SUMMARY>
				502	<BODY>
				503	<p>
				504	</p>
				505	<ul>
				506	<li>
				507	All code changes must be reviewed.
				508	You should expect that your code will be reviewed by other hackers,
				509	and that you will be assigned other hackers' code to review.
				510	Part of the review criteria will be that code obeys
				511	the coding standards in this document.
				512	</li>
				513	<li>
				514	You must write and check-in tests for new code that you write and old bugs you fix.
				515	There must be a unit test for every API function,
				516	and any previously failing case.
				517	Your work is not truly done until this activity is complete.
				518	Estimating tasks must include the time it takes to produce such tests.
				519	</li>
				520	<li>
				521	Your code must compile
				522	without any compilation error or warning messages whatsoever.
				523	If the compiler issues warnings that should be ignored,
				524	muffle those warnings using the
tunes@google.com	d6c053f	2013-09-19 17:26:22 +0000	[diff] [blame]	525	<code>UIOP:WITH-MUFFLED-COMPILER-CONDITIONS</code> and
				526	<code>UIOP:UNINTERESTING-COMPILER-CONDITIONS</code>
				527	framework (part of <code>UIOP</code>, part of <code>ASDF 3</code>),
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	528	either around the entire project, or around individual files
tunes@google.com	d6c053f	2013-09-19 17:26:22 +0000	[diff] [blame]	529	(using <code>ASDF</code>'s <code>:around-compile</code> hooks).
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	530	</li>
				531	<li>
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	532	All code should be checked in an appropriate source control system,
				533	in a way that allows for complete reproducibility of
				534	build, test and execution of
				535	the code that is, has been or may be deployed.
				536	</li>
				537	<li>
				538	You must run the "precheckin" tests, and each component must pass
				539	its unit tests successfully before you commit any code.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	540	</li>
				541	<li>
tunes@google.com	0c584cb	2012-10-11 17:06:57 +0000	[diff] [blame]	542	You should incorporate code coverage into your testing process.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	543	Tests are not sufficient
				544	if they do not cover all new and updated code;
				545	code that for whatever reason cannot be included in coverage results
				546	should be clearly marked as such including the reason.
				547	</li>
				548	<li>
				549	Many people develop on branches.
				550	You must get permission to undertake mass-changes
				551	(e.g. mass reindentations)
				552	so that we can coordinate in advance,
				553	and give branch residents time to get back on the mainline
				554	</li>
				555	</ul>
				556	</BODY>
				557	</STYLEPOINT>
				558	</CATEGORY>
				559	<CATEGORY title="Formatting">
tunes@google.com	d6c053f	2013-09-19 17:26:22 +0000	[diff] [blame]	560	<STYLEPOINT title="Spelling and Abbreviations">
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	561	<SUMMARY>
				562	<p>
				563	You must use correct spelling in your comments,
				564	and most importantly in your identifiers.
				565	</p>
				566	<p>
				567	When several correct spellings exist (including American vs English),
				568	and there isn't a consensus amongst developers as which to use,
				569	you should choose the shorter spelling.
				570	</p>
				571	<p>
mark@chromium.org	5684bbc	2013-07-12 18:53:13 +0000	[diff] [blame]	572	You must use only common and domain-specific abbreviations, and
				573	must be consistent with these abbreviations. You may abbreviate
				574	lexical variables of limited scope in order to avoid overly-long
				575	symbol names.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	576	</p>
				577	</SUMMARY>
				578	<BODY>
				579	<p>
				580	If you're not sure, consult a dictionary,
				581	Google for alternative spellings,
tunes@google.com	0c584cb	2012-10-11 17:06:57 +0000	[diff] [blame]	582	or ask a local expert.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	583	</p>
				584	<p>
				585	Here are examples of choosing the correct spelling:
				586	</p>
				587	<ul>
				588	<li>
				589	Use "complimentary" in the sense of a meal or beverage
				590	that is not paid for by the recipient, not "complementary".
				591	</li>
				592	<li>
				593	Use "existent" and "nonexistent", not "existant".
				594	Use "existence", not "existance".
				595	</li>
				596	<li>
				597	Use "hierarchy" not "heirarchy".
				598	</li>
				599	<li>
				600	Use "precede" not "preceed".
				601	</li>
				602	<li>
				603	Use "weird", not "wierd".
				604	</li>
				605	</ul>
				606	<p>
				607	Here are examples of choosing the shorter spelling:
				608	</p>
				609	<ul>
				610	<li>
				611	Use "canceled", not "cancelled"
				612	</li>
				613	<li>
				614	Use "queuing", not "queueing".
				615	</li>
				616	<li>
				617	Use "signaled", not "signalled";
				618	</li>
				619	<li>
				620	Use "traveled", not "travelled".
				621	</li>
				622	<li>
				623	Use "aluminum", not "aluminium"
				624	</li>
				625	<li>
				626	Use "oriented", not "orientated"
				627	</li>
				628	<li>
				629	Use "color", not "colour"
				630	</li>
				631	<li>
				632	Use "behavior", not "behaviour"
				633	</li>
				634	</ul>
				635	<p>
				636	Make appropriate exceptions for industry standard nomenclature/jargon,
				637	including plain misspellings.
				638	For instance:
				639	</p>
				640	<ul>
				641	<li>
				642	Use "referer", not "referrer", in the context of the HTTP protocol.
				643	</li>
				644	</ul>
				645
				646	</BODY>
				647	</STYLEPOINT>
				648	<STYLEPOINT title="Line length">
				649	<SUMMARY>
				650	You should format source code so that no line is longer than 100 characters.
				651	</SUMMARY>
				652	<BODY>
				653	<p>
				654	Some line length restriction is better than none at all.
tunes@google.com	13bb6e4	2012-10-15 20:57:01 +0000	[diff] [blame]	655	While old text terminals used to make 80 columns the standard,
				656	these days, allowing 100 columns seems better,
				657	since good style encourages the use of
				658	descriptive variables and function names.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	659	</p>
tunes@google.com	8c4c5ce	2012-10-12 23:16:43 +0000	[diff] [blame]	660
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	661	</BODY>
				662	</STYLEPOINT>
				663	<STYLEPOINT title="Indentation">
				664	<SUMMARY>
				665	<p>
tunes@google.com	0c584cb	2012-10-11 17:06:57 +0000	[diff] [blame]	666	Indent your code the way a properly configured GNU Emacs does.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	667	</p>
				668	<p>
tunes@google.com	cf1841c	2014-03-18 00:14:41 +0000	[diff] [blame]	669	Maintain a consistent indentation style throughout a project.
				670	</p>
				671	<p>
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	672	Indent carefully to make the code easier to understand.
				673	</p>
				674	</SUMMARY>
				675	<BODY>
				676	<p>
tunes@google.com	cf1841c	2014-03-18 00:14:41 +0000	[diff] [blame]	677	Common Lisp indentation in Emacs is provided by the cl-indent library.
				678	The latest version of cl-indent is packaged with
Ackermann Yuriy	7969290	2016-04-01 21:41:34 +1300	[diff] [blame]	679	<a HREF="https://www.common-lisp.net/project/slime/">SLIME</a>
tunes@google.com	cf1841c	2014-03-18 00:14:41 +0000	[diff] [blame]	680	(under contrib/slime-cl-indent.el). After installing SLIME, set up Emacs
				681	to load SLIME automatically using
Ackermann Yuriy	7969290	2016-04-01 21:41:34 +1300	[diff] [blame]	682	<a HREF="https://www.common-lisp.net/project/slime/doc/html/Loading-Contribs.html">these instructions</a>, adding slime-indentation to the list of
tunes@google.com	cf1841c	2014-03-18 00:14:41 +0000	[diff] [blame]	683	contrib libraries to be loaded in the call to slime-setup.
				684	</p>
				685	<p>
				686	Ideally, use the default indentation settings provided by
				687	slime-indentation. If necessary, customize indentation parameters to
				688	maintain a consistent indentation style throughout an existing project.
				689	Parameters can be customized using the :variables setting in
				690	define-common-lisp-style. Indentation of specific forms can be
				691	customized using the :indentation setting of define-common-lisp-style.
				692	This is particularly useful when creating forms that behave like macros
				693	or special operators that are indented differently than standard
				694	function calls (e.g. defun, labels, or let). Add a
Ackermann Yuriy	7969290	2016-04-01 21:41:34 +1300	[diff] [blame]	695	<a HREF="https://www.gnu.org/software/emacs/manual/html_node/emacs/Hooks.html">hook</a> to 'lisp-mode-hook that calls common-lisp-set-style to set
tunes@google.com	cf1841c	2014-03-18 00:14:41 +0000	[diff] [blame]	696	the appropriate style automatically.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	697	</p>
				698
				699
				700	<p>
				701	Use indentation to make complex function applications easier to read.
				702	When an application does not fit on one line
				703	or the function takes many arguments,
				704	consider inserting newlines between the arguments
				705	so that each one is on a separate line.
				706	However, do not insert newlines in a way that makes it hard to tell
				707	how many arguments the function takes
				708	or where an argument form starts and ends.
				709	</p>
				710	<BAD_CODE_SNIPPET>
				711	;; Bad
				712	(do-something first-argument second-argument (lambda (x)
				713	(frob x)) fourth-argument last-argument)
				714	</BAD_CODE_SNIPPET>
				715	<CODE_SNIPPET>
				716	;; Better
				717	(do-something first-argument
				718	second-argument
				719	#'(lambda (x) (frob x))
				720	fourth-argument
				721	last-argument)
				722	</CODE_SNIPPET>
				723	</BODY>
				724	</STYLEPOINT>
				725	<STYLEPOINT title="File Header">
				726	<SUMMARY>
				727	<p>
mark@chromium.org	5684bbc	2013-07-12 18:53:13 +0000	[diff] [blame]	728	You should include a description at the top of each source file.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	729	</p>
				730	<p>
mark@chromium.org	5684bbc	2013-07-12 18:53:13 +0000	[diff] [blame]	731	You should include neither authorship nor copyright information in a source file.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	732	</p>
				733	</SUMMARY>
				734	<BODY>
				735	<p>
mark@chromium.org	5684bbc	2013-07-12 18:53:13 +0000	[diff] [blame]	736	Every source file should begin with a brief description
				737	of the contents of that file.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	738	</p>
				739	<p>
mark@chromium.org	5684bbc	2013-07-12 18:53:13 +0000	[diff] [blame]	740	After that description, every file should start the code itself with an
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	741	<code>(in-package :<em>package-name</em>)</code> form.
				742	</p>
				743	<p>
				744	After that <code>in-package</code> form,
				745	every file should follow with any file-specific
				746	<code>(declaim (optimize ...))</code> declaration
tunes@google.com	d6c053f	2013-09-19 17:26:22 +0000	[diff] [blame]	747	that is not covered by an <code>ASDF</code> <code>:around-compile</code> hook.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	748	</p>
				749	<CODE_SNIPPET>
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	750	;;;; Variable length encoding for integers and floating point numbers.
				751
				752	(in-package #:varint)
				753	(declaim #.optimize-default)
				754	</CODE_SNIPPET>
				755	<p>
tunes@google.com	cf1841c	2014-03-18 00:14:41 +0000	[diff] [blame]	756	You should not include authorship information at the top of a file:
				757	better information is available from version control,
				758	and such a mention will only cause confusion and grief.
				759	Indeed, whoever was the main author at the time such a mention was included
				760	might not be who eventually made the most significant contributions to the file,
				761	and even less who is responsible for the file at the moment.
				762
mark@chromium.org	5684bbc	2013-07-12 18:53:13 +0000	[diff] [blame]	763	</p>
				764	<p>
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	765	You should not include copyright information in individual source code files.
				766	An exception is made for files meant to be disseminated as standalone.
				767	</p>
tunes@google.com	cf1841c	2014-03-18 00:14:41 +0000	[diff] [blame]	768
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	769
				770	</BODY>
				771	</STYLEPOINT>
				772	<STYLEPOINT title="Vertical white space">
				773	<SUMMARY>
				774	Vertical white space: one blank line between top-level forms.
				775	</SUMMARY>
				776	<BODY>
				777	<p>
				778	You should include one blank line between top-level forms,
				779	such as function definitions.
				780	Exceptionally, blank lines can be omitted
				781	between simple, closely related defining forms of the same kind,
				782	such as a group of related type declarations or constant definitions.
				783	</p>
				784	<CODE_SNIPPET>
				785	(defconstant +mix32+ #x12b9b0a1 "pi, an arbitrary number")
				786	(defconstant +mix64+ #x2b992ddfa23249d6 "more digits of pi")
				787
				788	(defconstant +golden-ratio32+ #x9e3779b9 "the golden ratio")
				789	(defconstant +golden-ratio64+ #xe08c1d668b756f82 "more digits of the golden ratio")
				790
				791	(defmacro incf32 (x y)
tunes@google.com	0c584cb	2012-10-11 17:06:57 +0000	[diff] [blame]	792	"Like INCF, but for integers modulo 2**32"
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	793	`(setf ,x (logand (+ ,x ,y) #xffffffff)))
				794	(defmacro incf64 (x y)
tunes@google.com	0c584cb	2012-10-11 17:06:57 +0000	[diff] [blame]	795	"Like INCF, but for integers modulo 2**64"
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	796	`(setf ,x (logand (+ ,x ,y) #xffffffffffffffff)))
				797	</CODE_SNIPPET>
				798	<p>
				799	Blank lines can be used to separate parts of a complicated function.
				800	Generally, however, you should break a large function into smaller ones
				801	instead of trying to make it more readable by adding vertical space.
				802	If you can't, you should document with a <code>;;</code> comment
				803	what each of the separated parts of the function does.
				804	</p>
				805	<p>
mark@chromium.org	5684bbc	2013-07-12 18:53:13 +0000	[diff] [blame]	806	You should strive to keep top-level forms,
				807	including comments but excluding the documentation string, of
				808	appropriate length; preferrably short. Forms extending beyond a
				809	single page should be rare and their use should be justfied.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	810	This applies to each of the forms in an <code>eval-when</code>,
				811	rather than to the <code>eval-when</code> itself.
				812	Additionally, <code>defpackage</code> forms may be longer,
				813	since they may include long lists of symbols.
				814	</p>
				815	</BODY>
				816	</STYLEPOINT>
				817	<STYLEPOINT title="Horizontal white space">
				818	<SUMMARY>
				819	Horizontal white space: none around parentheses. No tabs.
				820	</SUMMARY>
				821	<BODY>
				822	<p>
				823	You must not include extra horizontal whitespace
				824	before or after parentheses or around symbols.
				825	</p>
				826	<p>
				827	You must not place right parentheses by themselves on a line.
				828	A set of consecutive trailing parentheses must appear on the same line.
				829	</p>
				830	<BAD_CODE_SNIPPET>
				831	;; Very Bad
				832	( defun factorial ( limit )
				833	( let (( product 1 ))
				834	( loop for i from 1 upto limit
				835	do (setf product ( * product i ) ) )
				836	product
				837	)
				838	)
				839	</BAD_CODE_SNIPPET>
				840	<CODE_SNIPPET>
				841	;; Better
				842	(defun factorial (limit)
				843	(let ((product 1))
				844	(loop for i from 1 upto limit
				845	do (setf product (* product i)))
				846	product))
				847	</CODE_SNIPPET>
				848	<p>
				849	You should use only one space between forms.
				850	</p>
				851	<p>
				852	You should not use spaces to vertically align forms
				853	in the middle of consecutive lines.
				854	An exception is made when the code possesses
				855	an important yet otherwise not visible symmetry
				856	that you want to emphasize.
				857	</p>
				858	<BAD_CODE_SNIPPET>
				859	;; Bad
				860	(let* ((low 1)
				861	(high 2)
				862	(sum (+ (* low low) (* high high))))
				863	...)
				864	</BAD_CODE_SNIPPET>
				865	<CODE_SNIPPET>
				866	;; Better
				867	(let* ((low 1)
				868	(high 2)
				869	(sum (+ (* low low) (* high high))))
				870	...))
				871	</CODE_SNIPPET>
				872	<p>
				873	You must align nested forms if they occur across more than one line.
				874	</p>
				875	<BAD_CODE_SNIPPET>
				876	;; Bad
				877	(defun munge (a b c)
				878	(* (+ a b)
				879	c))
				880	</BAD_CODE_SNIPPET>
				881	<CODE_SNIPPET>
tunes@google.com	8c4c5ce	2012-10-12 23:16:43 +0000	[diff] [blame]	882	;; Better
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	883	(defun munge (a b c)
				884	(* (+ a b)
				885	c))
				886	</CODE_SNIPPET>
				887	<p>
				888	The convention is that the body of a binding form
				889	is indented two spaces after the form.
				890	Any binding data before the body is usually indented four spaces.
				891	Arguments to a function call are aligned with the first argument;
				892	if the first argument is on its own line,
				893	it is aligned with the function name.
				894	</p>
				895	<CODE_SNIPPET>
				896	(multiple-value-bind (a b c d)
				897	(function-returning-four-values x y)
				898	(declare (ignore c))
				899	(something-using a)
				900	(also-using b d))
				901	</CODE_SNIPPET>
				902	<p>
				903	An exception to the rule against lonely parentheses
				904	is made for an <code>eval-when</code> form around several definitions;
				905	in this case, include a comment <code>; eval-when</code>
				906	after the closing parenthesis.
				907	</p>
				908	<p>
				909	You must set your editor to
				910	avoid inserting tab characters in the files you edit.
				911	Tabs cause confusion when editors disagree
				912	on how many spaces they represent.
				913	In Emacs, do <code>(setq-default indent-tabs-mode nil)</code>.
				914	</p>
				915	</BODY>
				916	</STYLEPOINT>
				917	</CATEGORY>
				918
				919	<CATEGORY title="Documentation">
				920	<STYLEPOINT title="Document everything">
				921	<SUMMARY>
tunes@google.com	13bb6e4	2012-10-15 20:57:01 +0000	[diff] [blame]	922	You should use document strings on all visible functions
				923	to explain how to use your code.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	924	</SUMMARY>
				925	<BODY>
				926	<p>
tunes@google.com	13bb6e4	2012-10-15 20:57:01 +0000	[diff] [blame]	927	Unless some bit of code is painfully self-explanatory,
				928	document it with a documentation string (also known as docstring).
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	929	</p>
				930	<p>
tunes@google.com	13bb6e4	2012-10-15 20:57:01 +0000	[diff] [blame]	931	Documentation strings are destined to be read
				932	by the programmers who use your code.
				933	They can be extracted from functions, types, classes, variables and macros,
				934	and displayed by programming tools, such as IDEs,
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	935	or by REPL queries such as <code>(describe 'foo)</code>;
tunes@google.com	13bb6e4	2012-10-15 20:57:01 +0000	[diff] [blame]	936	web-based documentation or other reference works
				937	can be created based on them.
				938	Documentation strings are thus the perfect locus to document your API.
				939	They should describe how to use the code
				940	(including what pitfalls to avoid),
				941	as opposed to how the code works (and where more work is needed),
				942	which is what you'll put in comments.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	943	</p>
				944	<p>
tunes@google.com	13bb6e4	2012-10-15 20:57:01 +0000	[diff] [blame]	945	Supply a documentation string when defining
				946	top-level functions, types, classes, variables and macros.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	947	Generally, add a documentation string wherever the language allows.
				948	</p>
				949	<p>
				950	For functions, the docstring should describe the function's contract:
				951	what the function does,
				952	what the arguments mean,
				953	what values are returned,
				954	what conditions the function can signal.
				955	It should be expressed at the appropriate level of abstraction,
				956	explaining the intended meaning rather than, say, just the syntax.
				957	In documentation strings, capitalize the names of Lisp symbols,
				958	such as function arguments.
				959	For example, "The value of LENGTH should be an integer."
				960	</p>
				961	<CODE_SNIPPET>
tunes@google.com	8c4c5ce	2012-10-12 23:16:43 +0000	[diff] [blame]	962	(defun small-prime-number-p (n)
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	963	"Return T if N, an integer, is a prime number. Otherwise, return NIL."
				964	(cond ((or (< n 2))
				965	nil)
				966	((= n 2)
				967	t)
				968	((divisorp 2 n)
				969	nil)
				970	(t
				971	(loop for i from 3 upto (sqrt n) by 2
tunes@google.com	13bb6e4	2012-10-15 20:57:01 +0000	[diff] [blame]	972	never (divisorp i n)))))
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	973	</CODE_SNIPPET>
				974	<CODE_SNIPPET>
				975	(defgeneric table-clear (table)
				976	(:documentation
				977	"Like clrhash, empties the TABLE of all
				978	associations, and returns the table itself."))
				979	</CODE_SNIPPET>
				980	<p>
				981	A long docstring may usefully
				982	begin with a short, single-sentence summary,
				983	followed by the larger body of the docstring.
				984	</p>
				985	<p>
				986	When the name of a type is used,
				987	the symbol may be quoted by surrounding it with
				988	a back quote at the beginning and a single quote at the end.
				989	Emacs will highlight the type, and the highlighting serves
				990	as a cue to the reader that <kbd>M-.</kbd>
				991	will lead to the symbol's definition.
				992	</p>
				993	<CODE_SNIPPET>
				994	(defun bag-tag-expected-itinerary (bag-tag)
				995	"Return a list of `legacy-pnr-pax-segment' objects representing
				996	the expected itinerary of the `bag-tag' object, BAG-TAG."
				997	...)
				998	</CODE_SNIPPET>
				999	<p>
				1000	Every method of a generic function should be independently documented
				1001	when the specialization affects what the method does,
				1002	beyond what is described in its generic function's docstring.
				1003	</p>
				1004	<p>
				1005	When you fix a bug,
				1006	consider whether what the fixed code does is obviously correct or not;
				1007	if not, you must add a comment explaining
				1008	the reason for the code in terms of fixing the bug.
				1009	Adding the bug number, if any, is also recommended.
				1010	</p>
				1011	</BODY>
				1012	</STYLEPOINT>
				1013	<STYLEPOINT title="Comment semicolons">
				1014	<SUMMARY>
				1015	You must use the appropriate number of semicolons to introduce comments.
				1016	</SUMMARY>
				1017	<BODY>
tunes@google.com	13bb6e4	2012-10-15 20:57:01 +0000	[diff] [blame]	1018	<p>
				1019	Comments are explanations to the future maintainers of the code.
				1020	Even if you're the only person who will ever see and touch the code,
				1021	even if you're either immortal and never going to quit,
				1022	or unconcerned with what happens after you leave
				1023	(and have your code self-destruct in such an eventuality),
				1024	you may find it useful to comment your code.
				1025	Indeed, by the time you revisit your code,
				1026	weeks, months or years later,
				1027	you will find yourself a different person from the one who wrote it,
				1028	and you will be grateful to that previous self
				1029	for making the code readable.
				1030	</p>
				1031	<p>
				1032	You must comment anything complicated
				1033	so that the next developer can understand what's going on.
				1034	(Again, the "hit by a truck" principle.)
				1035	</p>
				1036	<p>
				1037	Also use comments as a way to guide those who read the code,
				1038	so they know what to find where.
				1039	</p>
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	1040	<ul>
				1041	<li>
				1042	File headers and important comments
				1043	that apply to large sections of code in a source file
				1044	should begin with four semicolons.
				1045	</li>
				1046	<li>
				1047	You should use three semicolons
				1048	to begin comments that apply to just
				1049	one top-level form or small group of top-level forms.
				1050	</li>
				1051	<li>
				1052	Inside a top-level form, you should use two semicolons
				1053	to begin a comment if it appears between lines.
				1054	</li>
				1055	<li>
				1056	You should use one semicolon if it is a parenthetical remark
				1057	and occurs at the end of a line.
				1058	You should use spaces to separate the comment
				1059	from the code it refers to so the comment stands out.
				1060	You should try to vertically align
				1061	consecutive related end-of-line comments.
				1062	</li>
				1063	</ul>
				1064	<CODE_SNIPPET>
				1065	;;;; project-euler.lisp
				1066	;;;; File-level comments or comments for large sections of code.
				1067
Ackermann Yuriy	7969290	2016-04-01 21:41:34 +1300	[diff] [blame]	1068	;;; Problems are described in more detail here: https://projecteuler.net/
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	1069
				1070	;;; Divisibility
				1071	;;; Comments that describe a group of definitions.
				1072
tunes@google.com	8c4c5ce	2012-10-12 23:16:43 +0000	[diff] [blame]	1073	(defun divisorp (d n)
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	1074	(zerop (mod n d)))
				1075
				1076	(defun proper-divisors (n)
				1077	...)
				1078
				1079	(defun divisors (n)
				1080	(cons n (proper-divisors n)))
				1081
				1082	;;; Prime numbers
				1083
tunes@google.com	8c4c5ce	2012-10-12 23:16:43 +0000	[diff] [blame]	1084	(defun small-prime-number-p (n)
				1085	(cond ((or (< n 2))
				1086	nil)
				1087	((= n 2) ; parenthetical remark here
				1088	t) ; continuation of the remark
tunes@google.com	13bb6e4	2012-10-15 20:57:01 +0000	[diff] [blame]	1089	((divisorp 2 n)
tunes@google.com	8c4c5ce	2012-10-12 23:16:43 +0000	[diff] [blame]	1090	nil) ; different remark
				1091	;; Comment that applies to a section of code.
				1092	(t
				1093	(loop for i from 3 upto (sqrt n) by 2
tunes@google.com	13bb6e4	2012-10-15 20:57:01 +0000	[diff] [blame]	1094	never (divisorp i n)))))
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	1095	</CODE_SNIPPET>
				1096	<p>
				1097	You should include a space between the semicolon and the text of the comment.
				1098	</p>
				1099	</BODY>
				1100	</STYLEPOINT>
				1101	<STYLEPOINT title="Grammar and punctuation">
				1102	<SUMMARY>
				1103	You should punctuate documentation correctly.
				1104	</SUMMARY>
				1105	<BODY>
				1106	<p>
				1107	When a comment is a full sentence,
				1108	you should capitalize the initial letter of the first word
				1109	and end the comment with a period.
				1110	In general, you should use correct punctuation.
				1111	</p>
				1112	</BODY>
				1113	</STYLEPOINT>
				1114	<STYLEPOINT title="Attention Required">
				1115	<SUMMARY>
mark@chromium.org	5684bbc	2013-07-12 18:53:13 +0000	[diff] [blame]	1116	You must follow the convention of using TODO comments
				1117	for code requiring special attention.
				1118	For code using unobvious forms, you must include a comment.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	1119	</SUMMARY>
				1120	<BODY>
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	1121	<p>
mark@chromium.org	5684bbc	2013-07-12 18:53:13 +0000	[diff] [blame]	1122	For comments requiring special attention, such as
				1123	incomplete code, todo items, questions, breakage, and danger,
				1124	include a TODO comment indicating the type of problem,
				1125	its nature, and any notes on how it may be addressed.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	1126	</p>
				1127	<p>
				1128	The comments begin with <code>TODO</code> in all capital letters,
tunes@google.com	cf1841c	2014-03-18 00:14:41 +0000	[diff] [blame]	1129	followed by the
				1130
				1131	name, e-mail address, or other identifier
				1132	of the person
				1133	with the best context about the problem referenced by the <code>TODO</code>.
				1134	The main purpose is to have a consistent <code>TODO</code> that
				1135	can be searched to find out how to get more details upon
				1136	request. A <code>TODO</code> is not a commitment that the
				1137	person referenced will fix the problem. Thus when you create
				1138	a <code>TODO</code>,
				1139	it is almost always your
				1140	name
				1141	that is given.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	1142	</p>
				1143	<p>
				1144	When signing comments,
				1145	you should use your username (for code within the company)
				1146	or full email address (for code visible outside the company),
				1147	not just initials.
				1148
				1149	</p>
				1150	<CODE_SNIPPET>
				1151	;;--- TODO(george@gmail.com): Refactor to provide a better API.
				1152	</CODE_SNIPPET>
				1153	<p>
				1154	Be specific when indicating times or software releases
tunes@google.com	cf1841c	2014-03-18 00:14:41 +0000	[diff] [blame]	1155	in a TODO comment and use
Ackermann Yuriy	7969290	2016-04-01 21:41:34 +1300	[diff] [blame]	1156	<a HREF="https://www.w3.org/TR/NOTE-datetime">YYYY-MM-DD</a>
tunes@google.com	cf1841c	2014-03-18 00:14:41 +0000	[diff] [blame]	1157	format for dates to make automated processing of such dates easier,
				1158	e.g., 2038-01-20 for the end of the 32-bit signed <code>time_t</code>.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	1159	</p>
				1160	<CODE_SNIPPET>
tunes@google.com	cf1841c	2014-03-18 00:14:41 +0000	[diff] [blame]	1161	;;--- TODO(brown): Remove this code after release 1.7 or before 2012-11-30.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	1162	</CODE_SNIPPET>
mark@chromium.org	5684bbc	2013-07-12 18:53:13 +0000	[diff] [blame]	1163	<p>
				1164	For code that uses unobvious forms to accomplish a task, you must include a comment
				1165	stating the purpose of the form and the task it accomplishes.
				1166	</p>
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	1167	</BODY>
				1168	</STYLEPOINT>
				1169	<STYLEPOINT title="Domain-Specific Languages">
				1170	<SUMMARY>
				1171	You should document DSLs and
				1172	any terse program in a DSL.
				1173	</SUMMARY>
				1174	<BODY>
				1175	<p>
				1176	You should design your Domain Specific Language
				1177	to be easy to read and understand by people familiar with the domain.
				1178	</p>
				1179	<p>
				1180	You must properly document all your Domain Specific Language.
				1181	</p>
				1182	<p>
				1183	Sometimes, your DSL is designed for terseness.
				1184	In that case, it is important to document what each program does,
				1185	if it's not painfully obvious from the context.
				1186	</p>
				1187	<p>
				1188	Notably, when you use regular expressions
				1189	(e.g. with the <code>CL-PPCRE</code> package),
				1190	you MUST ALWAYS put in a comment
				1191	(usually a two-semicolon comment on the previous line)
				1192	explaining, at least basically, what the regular expression does,
				1193	or what the purpose of using it is.
				1194	The comment need not spell out every bit of the syntax, but
				1195	it should be possible for someone to follow the logic of the code
				1196	without actually parsing the regular expression.
				1197	</p>
				1198	</BODY>
				1199	</STYLEPOINT>
				1200
				1201	</CATEGORY>
				1202
				1203	<CATEGORY title="Naming">
				1204	<STYLEPOINT title="Symbol guidelines">
				1205	<SUMMARY>
				1206	You should use lower case.
tunes@google.com	d6c053f	2013-09-19 17:26:22 +0000	[diff] [blame]	1207	You should follow the rules for <a href="#Spelling_and_Abbreviations">Spelling and Abbreviations</a>
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	1208	You should follow punctuation conventions.
				1209	</SUMMARY>
				1210	<BODY>
				1211	<p>
				1212	Use lower case for all symbols.
				1213	Consistently using lower case makes searching for symbol names easier
				1214	and is more readable.
				1215	</p>
				1216	<p>
				1217	Note that Common Lisp is case-converting,
				1218	and that the <code>symbol-name</code> of your symbols
				1219	will be upper case.
				1220	Because of this case-converting,
				1221	attempts to distinguish symbols by case are defeated,
				1222	and only result in confusion.
				1223	While it is possible to escape characters in symbols
				1224	to force lower case,
				1225	you should not use this capability
				1226	unless this is somehow necessary
				1227	to interoperate with third-party software.
				1228	</p>
				1229	<p>
				1230	Place hyphens between all the words in a symbol.
				1231	If you can't easily say an identifier out loud,
				1232	it is probably badly named.
				1233	</p>
				1234	<p>
				1235	You must not use <code>"/"</code> or <code>"."</code>
				1236	instead of <code>"-"</code>
				1237	unless you have a well-documented overarching reason to,
				1238	and permission from other hackers who review your proposal.
				1239	</p>
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	1240	<p>
tunes@google.com	d6c053f	2013-09-19 17:26:22 +0000	[diff] [blame]	1241	See the section on <a href="#Spelling_and_Abbreviations">Spelling and Abbreviations</a>
				1242	for guidelines on using abbreviations.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	1243	</p>
				1244	<BAD_CODE_SNIPPET>
				1245	;; Bad
				1246	(defvar default-username "Ann")
				1247	(defvar max-widget-cnt 200)
				1248	</BAD_CODE_SNIPPET>
				1249	<CODE_SNIPPET>
				1250	;; Better
				1251	(defvar default-user-name "Ann")
				1252	(defvar maximum-widget-count 200)
				1253	</CODE_SNIPPET>
				1254	<p>
				1255	There are conventions in Common Lisp
				1256	for the use of punctuation in symbols.
				1257	You should not use punctuation in symbols outside these conventions.
				1258	</p>
				1259	<p>
				1260	Unless the scope of a variable is very small,
				1261	do not use overly short names like
				1262	<code>i</code> and <code>zq</code>.
				1263	</p>
				1264	</BODY>
				1265	</STYLEPOINT>
				1266	<STYLEPOINT title="Denote intent, not content">
				1267	<SUMMARY>
				1268	Name your variables according to their intent,
				1269	not their content.
				1270	</SUMMARY>
				1271	<BODY>
				1272	<p>
				1273	You should name a variable according
				1274	to the high-level concept that it represents,
				1275	not according to the low-level implementation details
				1276	of how the concept is represented.
				1277	</p>
				1278	<p>
				1279	Thus, you should avoid embedding
				1280	data structure or aggregate type names,
				1281	such as <code>list</code>, <code>array</code>, or
				1282	<code>hash-table</code> inside variable names,
				1283	unless you're writing a generic algorithm that applies to
				1284	arbitrary lists, arrays, hash-tables, etc.
				1285	In that case it's perfectly OK to name a variable
				1286	<code>list</code> or <code>array</code>.
				1287	</p>
				1288	<p>
				1289	Indeed, you should be introducing new abstract data types
				1290	with <code>DEFCLASS</code> or <code>DEFTYPE</code>,
				1291	whenever a new kind of intent appears for objects in your protocols.
				1292	Functions that manipulate such objects generically may then
				1293	use variables the name of which reflect that abstract type.
				1294	</p>
				1295	<p>
				1296	For example, if a variable's value is always a row
				1297	(or is either a row or <code>NIL</code>),
				1298	it's good to call it <code>row</code> or <code>first-row</code>
				1299	or something like that.
				1300	It is alright is <code>row</code> has been
mark@chromium.org	8190c13	2013-03-21 16:03:26 +0000	[diff] [blame]	1301	<code>DEFTYPE</code>'d to <code>STRING</code> —
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	1302	precisely because you have abstracted the detail away,
				1303	and the remaining salient point is that it is a row.
				1304	You should not name the variable <code>STRING</code> in this context,
				1305	except possibly in low-level functions that specifically manipulate
				1306	the innards of rows to provide the suitable abstraction.
				1307	</p>
				1308	<p>
				1309	Be consistent.
				1310	If a variable is named <code>row</code> in one function,
				1311	and its value is being passed to a second function,
				1312	then call it <code>row</code> rather than, say, <code>value</code>
				1313	(this was a real case).
				1314	</p>
				1315	</BODY>
				1316	</STYLEPOINT>
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	1317	<STYLEPOINT title="Global variables and constants">
				1318	<SUMMARY>
				1319	Name globals according to convention.
				1320	</SUMMARY>
				1321	<BODY>
				1322	<p>
				1323	The names of global constants should start and end
				1324	with plus characters.
				1325	</p>
				1326	<p>
				1327	Global variable names should start and end with asterisks
				1328	(also known in this context as earmuffs).
				1329	</p>
				1330	<p>
				1331	In some projects, parameters that are not meant
				1332	to be usually modified or bound under normal circumstances
				1333	(but may be during experimentation or exceptional situations)
				1334	should start (but do not end) with a dollar sign.
				1335	If such a convention exists within your project,
				1336	you should follow it consistently.
				1337	Otherwise, you should avoid naming variables like this.
				1338	</p>
				1339	<p>
				1340	Common Lisp does not have global lexical variables,
				1341	so a naming convention is used to ensure that globals,
				1342	which are dynamically bound,
				1343	never have names that overlap with local variables.
				1344	It is possible to fake global lexical variables
				1345	with a differently named global variable
				1346	and a <code>DEFINE-SYMBOL-MACRO</code>.
tunes@google.com	0c584cb	2012-10-11 17:06:57 +0000	[diff] [blame]	1347	You should not use this trick,
				1348	unless you first publish a library that abstracts it away.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	1349	</p>
				1350	<CODE_SNIPPET>
				1351	(defconstant +hash-results+ #xbd49d10d10cbee50)
				1352
				1353	(defvar maximum-search-depth 100)
				1354	</CODE_SNIPPET>
				1355	</BODY>
				1356	</STYLEPOINT>
				1357	<STYLEPOINT title="Predicate names">
				1358	<SUMMARY>
mark@chromium.org	5684bbc	2013-07-12 18:53:13 +0000	[diff] [blame]	1359	Names of predicate functions and variables end with a <code>"P"</code>.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	1360	</SUMMARY>
				1361	<BODY>
				1362	<p>
mark@chromium.org	5684bbc	2013-07-12 18:53:13 +0000	[diff] [blame]	1363	You should name boolean-valued functions and variables with a
				1364	trailing <code>"P"</code> or <code>"-P"</code>,
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	1365	to indicate they are predicates.
				1366	Generally, you should use
				1367	<code>"P"</code> when the rest of the function name is one word
				1368	and <code>"-P"</code> when it is more than one word.
				1369	</p>
				1370	<p>
tunes@google.com	0c584cb	2012-10-11 17:06:57 +0000	[diff] [blame]	1371	A rationale for this convention is given in
				1372	<a href="http://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node69.html">the CLtL2 chapter on predicates</a>.
				1373	</p>
				1374	<p>
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	1375	For uniformity, you should follow the convention above,
				1376	and not one of the alternatives below.
				1377	</p>
				1378	<p>
tunes@google.com	0c584cb	2012-10-11 17:06:57 +0000	[diff] [blame]	1379	An alternative rule used in some existing packages
				1380	is to always use <code>"-P"</code>.
				1381	Another alternative rule used in some existing packages
				1382	is to always use <code>"?"</code>.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	1383	When you develop such a package,
				1384	you must be consistent with the rest of the package.
				1385	When you start a new package,
				1386	you should not use such an alternative rule
tunes@google.com	0c584cb	2012-10-11 17:06:57 +0000	[diff] [blame]	1387	without a very good documented reason.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	1388	</p>
				1389	</BODY>
				1390	</STYLEPOINT>
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	1391	<STYLEPOINT title="Omit library prefixes">
				1392	<SUMMARY>
				1393	You should not include a library or package name
				1394	as a prefix within the name of symbols.
				1395	</SUMMARY>
				1396	<BODY>
				1397	<p>
				1398	When naming a symbol (external or internal) in a package,
				1399	you should not include the package name
				1400	as a prefix within the name of the symbol.
				1401	Naming a symbol this way makes it awkward to use
				1402	from a client package accessing the symbol
				1403	by qualifying it with a package prefix,
				1404	where the package name then appears twice
				1405	(once as a package prefix,
				1406	another time as a prefix within the symbol name).
				1407	</p>
				1408	<BAD_CODE_SNIPPET>
				1409	;; Bad
				1410	(in-package #:varint)
				1411	(defun varint-length64 () ... )
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	1412
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	1413	(in-package #:client-code)
				1414	(defconst +padding+ (varint:varint-length64 +end-token+))
				1415	</BAD_CODE_SNIPPET>
				1416	<CODE_SNIPPET>
				1417	;; Better
				1418	(in-package #:varint)
				1419	(defun length64 () ... )
				1420
				1421	(in-package #:client-code)
				1422	(defconst +padding+ (varint:length64 +end-token+))
				1423	</CODE_SNIPPET>
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	1424	<p>
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	1425	An exception to the above rule would be to include a prefix
				1426	for the names of variables that would otherwise be expected to clash
				1427	with variables in packages that use the current one.
				1428	For instance, <code>ASDF</code> exports a variable <code>ASDF-VERBOSE</code>
				1429	that controls the verbosity of <code>ASDF</code> only,
				1430	rather than of the entire Lisp program.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	1431	</p>
				1432	</BODY>
				1433	</STYLEPOINT>
				1434	<STYLEPOINT title="Packages">
				1435	<SUMMARY>
				1436	Use packages appropriately.
				1437	</SUMMARY>
				1438	<BODY>
				1439	<p>
				1440	Lisp packages are used to demarcate namespaces.
				1441	Usually, each system has its own namespace.
				1442	A package has a set of external symbols,
				1443	which are intended to be used from outside the package,
				1444	in order to allow other modules to use this module's facilities.
				1445	</p>
				1446	<p>
				1447	The internal symbols of a package
				1448	should never be referred to from other packages.
				1449	That is, you should never have to use
				1450	the double-colon <code>::</code> construct.
				1451	(e.g. <code>QUAKE::HIDDEN-FUNCTION</code>).
				1452	If you need to use double-colons to write real production code,
				1453	something is wrong and needs to be fixed.
				1454	</p>
				1455	<p>
				1456	As an exception,
				1457	unit tests may use the internals of the package being tested.
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	1458	So when you refactor, watch out for
				1459	internals used by the package's unit tests.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	1460	</p>
				1461	<p>
				1462	The <code>::</code> construct is also useful for very temporary hacks,
				1463	and at the REPL.
				1464	But if the symbol really is part of
				1465	the externally-visible definition of the package,
				1466	export it.
				1467	</p>
				1468	<p>
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	1469	You may find that some internal symbols represent concepts
				1470	you usually want to abstract away and hide under the hood,
				1471	yet at times are necessary to expose for various extensions.
				1472	For the former reason, you do not want to export them,
				1473	yet for the latter reason, you have to export them.
				1474	The solution is to have two different packages,
				1475	one for your normal users to use, and
				1476	another for the implementation and its extenders to use.
				1477	</p>
				1478	<p>
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	1479	Each package is one of two types:
				1480	</p>
				1481	<ul>
				1482	<li>
				1483	Intended to be included
				1484	in the <code>:use</code> specification of other packages.
				1485	If package <code>A</code> "uses" package <code>B</code>,
				1486	then the external symbols of package <code>B</code>
				1487	can be referenced from within package <code>A</code>
				1488	without a package prefix.
				1489	We mainly use this for low-level modules
				1490	that provide widely-used facilities.
				1491	</li>
				1492	<li>
				1493	Not intended to be "used".
				1494	To reference a facility provided by package <code>B</code>,
				1495	code in package <code>A</code> must use an explicit package prefix,
				1496	e.g. <code>B:DO-THIS</code>.
				1497	</li>
				1498	</ul>
				1499	<p>
				1500	If you add a new package, it should always be of the second type,
				1501	unless you have a special reason and get permission.
				1502	Usually a package is designed to be one or the other,
				1503	by virtue of the names of the functions.
				1504	For example, if you have an abstraction called <code>FIFO</code>,
				1505	and it were in a package of the first type
				1506	you'd have functions named things like
				1507	<code>FIFO-ADD-TO</code> and <code>FIFO-CLEAR-ALL</code>.
				1508	If you used a package of the second type,
				1509	you'd have names like <code>ADD-TO</code> and <code>CLEAR-ALL</code>,
				1510	because the callers would be saying
				1511	<code>FIFO:ADD-TO</code> and <code>FIFO:CLEAR-ALL</code>.
				1512	(<code>FIFO:FIFO-CLEAR-ALL</code> is redundant and ugly.)
				1513	</p>
				1514	<p>
				1515	Another good thing about packages is that
				1516	your symbol names won't "collide" with the names of other packages,
				1517	except the ones your packages "uses".
				1518	So you have to stay away from symbols
				1519	that are part of the Lisp implementation (since you always "use" that)
				1520	and that are part of any other packages you "use",
				1521	but otherwise you are free to make up your own names,
				1522	even short ones, and not worry about some else
				1523	having used the same name.
				1524	You're isolated from each other.
				1525	</p>
				1526	<p>
				1527	Your package must not shadow (and thus effectively redefine)
				1528	symbols that are part of the Common Lisp language.
				1529	There are certain exceptions,
				1530	but they should be very well-justified and extremely rare:
				1531	</p>
				1532	<ul>
				1533	<li>
				1534	If you are explicitly replacing a Common Lisp symbol
				1535	by a safer or more featureful version.
				1536	</li>
				1537	<li>
				1538	If you are defining a package not meant to be "used",
				1539	and have a good reason to export a symbol
				1540	that clashes with Common Lisp,
				1541	such as <code>log:error</code> and <code>log:warn</code>
				1542	and so on.
				1543	</li>
				1544	</ul>
				1545	</BODY>
				1546	</STYLEPOINT>
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	1547	</CATEGORY>
				1548
				1549	<CATEGORY title="Language usage guidelines">
				1550	<STYLEPOINT title="Mostly Functional Style">
				1551	<SUMMARY>
				1552	You should avoid side-effects when they are not necessary.
				1553	</SUMMARY>
				1554	<BODY>
				1555	<p>
				1556	Lisp is best used as a "mostly functional" language.
				1557	</p>
				1558	<p>
				1559	Avoid modifying local variables, try rebinding instead.
				1560	</p>
				1561	<p>
				1562	Avoid creating objects and the SETFing their slots.
				1563	It's better to set the slots during initialization.
				1564	</p>
				1565	<p>
				1566	Make classes as immutable as possible, that is, avoid giving slots
				1567	setter functions if at all possible.
				1568	</p>
				1569	<p>
				1570	Using a mostly functional style makes it much easier
				1571	to write concurrent code that is thread-safe.
				1572	It also makes it easier to test the code.
				1573	</p>
				1574	</BODY>
				1575	</STYLEPOINT>
				1576	<STYLEPOINT title="Recursion">
				1577	<SUMMARY>
tunes@google.com	13bb6e4	2012-10-15 20:57:01 +0000	[diff] [blame]	1578	You should favor iteration over recursion.
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	1579	</SUMMARY>
				1580	<BODY>
				1581	<p>
				1582	Common Lisp systems are not required to implement
				1583	function calls from tail positions without leaking stack space
mark@chromium.org	8190c13	2013-03-21 16:03:26 +0000	[diff] [blame]	1584	— which is known as proper tail calls (PTC),
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	1585	tail call elimination (TCE),
				1586	or tail call optimization (TCO).
				1587	This means that indefinite recursion through tail calls
				1588	may quickly blow out the stack,
				1589	which hampers functional programming.
				1590	Still, most serious implementations (including SBCL and CCL)
				1591	do implement proper tail calls, but with restrictions:
				1592	</p>
				1593	<ul>
				1594	<li>
				1595	The <code>(DECLARE (OPTIMIZE ...))</code> settings
				1596	must favor <code>SPEED</code> enough and
				1597	not favor <code>DEBUG</code> too much,
				1598	for some compiler-dependent meanings of "enough" and "too much".
				1599	(For instance, in SBCL, you should avoid <code>(SPEED 0)</code>
				1600	and <code>(DEBUG 3)</code> to achieve proper tail calls.)
				1601	</li>
				1602	<li>
				1603	There should not be dynamic bindings around the call
				1604	(even though some Scheme compilers are able to properly treat
				1605	such dynamic bindings, called parameters in Scheme parlance).
				1606	</li>
				1607	</ul>
				1608	<p>
				1609	For compatibility with all compilers and optimization settings,
				1610	and to avoid stack overflow when debugging,
				1611	you should prefer iteration or the built in mapping functions
				1612	to relying on proper tail calls.
				1613	</p>
				1614	<p>
				1615	If you do rely on proper tail calls,
				1616	you must prominently document the fact,
				1617	and take appropriate measures to ensure an appropriate compiler is used
				1618	with appropriate optimization settings.
				1619	For fully portable code, you may have to use trampolines instead.
				1620	</p>
				1621	</BODY>
				1622	</STYLEPOINT>
				1623	<STYLEPOINT title="Special variables">
				1624	<SUMMARY>
				1625	Use special variables sparingly.
				1626	</SUMMARY>
				1627	<BODY>
				1628	<p>
				1629	Using Lisp "special" (dynamically bound) variables
				1630	as implicit arguments to functions should be used sparingly,
				1631	and only in cases where it won't surprise the person reading the code,
				1632	and where it offers significant benefits.
				1633	</p>
				1634	<p>
tunes@google.com	13bb6e4	2012-10-15 20:57:01 +0000	[diff] [blame]	1635	Indeed, each special variable constitutes state.
				1636	Developers have to mentally track the state of all relevant variables
				1637	when trying to understand what the code does and how it does it;
				1638	tests have to be written and run with all relevant combinations;
				1639	to isolate some activity, care has to be taken to locally bind
				1640	all relevant variables, including those of indirectly used modules.
				1641	They can hide precious information from being printed in a backtrace.
				1642	Not only is there overhead associated to each new variable,
				1643	but interactions between variables
				1644	can make the code exponentially more complex
				1645	as the number of such variables increases.
				1646	The benefits have to match the costs.
				1647	</p>
				1648	<p>
				1649	Note though that a Lisp special variable is not a global variable
				1650	in the sense of a global variable in, say, BASIC or C.
				1651	As special variables can be dynamically bound to a local value,
				1652	they are much more powerful than
				1653	global value cells where all users necessarily interfere with each other.
				1654	</p>
				1655	<p>
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	1656	Good candidates for such special variables
				1657	are items for which "the current" can be naturally used as prefix,
				1658	such as "the current database connection" or
				1659	"the current business data source".
				1660	They are singletons as far as the rest of the code is concerned,
				1661	and often passing them as an explicit argument
				1662	does not add anything to the readability or maintainability
				1663	of the source code in question.
				1664	</p>
				1665	<p>
				1666	They can make it easier to write code that can be refactored.
				1667	If you have a request processing chain,
				1668	with a number of layers that all operate upon a "current" request,
				1669	passing the request object explicitly to every function
				1670	requires that every function in the chain have a request argument.
				1671	Factoring out code into new functions often requires
				1672	that these functions also have this argument,
				1673	which clutters the code with boilerplate.
				1674	</p>
				1675	<p>
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	1676	You should treat special variables
				1677	as though they are per-thread variables.
tunes@google.com	13bb6e4	2012-10-15 20:57:01 +0000	[diff] [blame]	1678	By default, you should leave a special variable
				1679	with no top-level binding at all,
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	1680	and each thread of control
				1681	that needs the variable should bind it explicitly.
				1682	This will mean that any incorrect use of the variable
				1683	will result in an "unbound variable" error, and
				1684	each thread will see its own value for the variable.
tunes@google.com	13bb6e4	2012-10-15 20:57:01 +0000	[diff] [blame]	1685	Variables with a default global value should usually be
				1686	locally bound at thread creation time.
				1687	You should use suitable infrastructure
				1688	to automate the appropriate declaration of such variables.
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	1689	</p>
				1690
				1691	</BODY>
				1692	</STYLEPOINT>
				1693	<STYLEPOINT title="Assignment">
				1694	<SUMMARY>
				1695	Be consistent in assignment forms.
				1696	</SUMMARY>
				1697	<BODY>
				1698	<p>
				1699	There are several styles for dealing with assignment and side-effects;
				1700	whichever a given package is using,
				1701	keep using the same consistently when hacking said package.
				1702	Pick a style that makes sense when starting a new package.
				1703	</p>
				1704	<p>
				1705	Regarding multiple assignment in a same form, there are two schools:
				1706	the first style groups as many assignments as possible into a single
				1707	<code>SETF</code> or <code>PSETF</code> form
				1708	thus minimizing the number of forms with side-effects;
				1709	the second style splits assignments into as many individual
				1710	<code>SETF</code> (or <code>SETQ</code>, see below) forms as possible,
				1711	to maximize the chances of locating forms that modify a kind of place
				1712	by grepping for <code>(setf (foo ...</code>.
				1713	A grep pattern must actually contain as many place-modifying forms
				1714	as you may use in your programs, which may make this rationale either
				1715	convincing or moot depending on the rest of the style of your code.
				1716	You should follow the convention used in the package you are hacking.
				1717	We recommend the first convention for new packages.
				1718	</p>
				1719	<p>
				1720	Regarding <code>SETF</code> and <code>SETQ</code>,
				1721	there are two schools:
				1722	this first regards <code>SETQ</code>
				1723	as an archaic implementation detail,
				1724	and avoids it entirely in favor of <code>SETF</code>;
				1725	the second regards <code>SETF</code>
				1726	as an additional layer of complexity,
				1727	and avoids it in favor of <code>SETQ</code> whenever possible
				1728	(i.e. whenever the assigned place is a variable or symbol-macro).
				1729	You should follow the convention used in the package you are hacking.
				1730	We recommend the first convention for new packages.
				1731	</p>
				1732	<p>
				1733	In the spirit of a mostly pure functional style,
				1734	which makes testing and maintenance easier,
				1735	we invite you to consider how to do things with the fewest assignments required.
				1736	</p>
				1737	</BODY>
				1738	</STYLEPOINT>
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	1739	<STYLEPOINT title="Assertions and Conditions">
				1740	<SUMMARY>
				1741	You must make proper usage of assertions and conditions.
				1742	</SUMMARY>
				1743	<BODY>
				1744	<ul>
				1745	<li>
				1746	<code>ASSERT</code> should be used ONLY to detect internal bugs.
				1747	Code should <code>ASSERT</code> invariants whose failure indicates
				1748	that the software is itself broken.
				1749	Incorrect input should be handled properly at runtime,
				1750	and must not cause an assertion violation.
				1751	The audience for an <code>ASSERT</code> failure is a developer.
				1752	Do not use the data-form and argument-form in <code>ASSERT</code>
				1753	to specify a condition to signal.
				1754	It's fine to use them to print out a message for debugging purposes
				1755	(and since it's only for debugging, there's no issue of
				1756	internationalization).
				1757	</li>
				1758	<li>
				1759	<code>CHECK-TYPE</code>,
				1760	<code>ETYPECASE</code> are also forms of assertion.
				1761	When one of these fails, that's a detected bug.
				1762	You should prefer to use <code>CHECK-TYPE</code>
				1763	over (DECLARE (TYPE ...))
				1764	for the inputs of functions.
				1765	</li>
				1766	<li>
				1767	Your code should use assertions and type checks liberally.
				1768	The sooner a bug is discovered, the better!
				1769	Only code in the critical path for performance
				1770	and internal helpers should eschew
				1771	explicit assertions and type checks.
				1772	</li>
				1773	<li>
				1774	Invalid input, such as files that are read
				1775	but do not conform to the expected format,
				1776	should not be treated as assertion violations.
				1777	Always check to make sure that input is valid,
				1778	and take appropriate action if it is not,
				1779	such as signalling a real error.
				1780	</li>
				1781	<li>
				1782	<code>ERROR</code> should be used
				1783	to detect problems with user data, requests, permissions, etc.,
				1784	or to report "unusual outcomes" to the caller.
				1785	</li>
				1786	<li>
				1787	<code>ERROR</code> should always be called
				1788	with an explicit condition type;
				1789	it should never simply be called with a string.
				1790	This enables internationalization.
				1791	</li>
				1792	<li>
				1793	Functions that report unusual outcomes
				1794	by signaling a condition should say so explicitly in their contracts
				1795	(their textual descriptions, in documentation and docstrings etc.).
				1796	When a function signals a condition
				1797	that is not specified by its contract, that's a bug.
				1798	The contract should specify the condition class(es) clearly.
				1799	The function may then signal any condition
				1800	that is a type-of any of those conditions.
				1801	That is, signaling instances of subclasses
				1802	of the documented condition classes is fine.
				1803	</li>
				1804	<li>
				1805	Complex bug-checks may need to use <code>ERROR</code>
				1806	instead of <code>ASSERT</code>.
				1807
				1808	</li>
				1809	<li>
				1810	When writing a server, you must not call <code>WARN</code>.
				1811	Instead, you should use the appropriate logging framework.
				1812
				1813	</li>
				1814	<li>
				1815	Code must not call <code>SIGNAL</code>.
				1816	Instead, use <code>ERROR</code> or <code>ASSERT</code>.
				1817	</li>
				1818	<li>
				1819	Code should not use <code>THROW</code> and <code>CATCH</code>;
				1820	instead use the <code>restart</code> facility.
				1821	</li>
				1822	<li>
				1823	Code should not generically handle all conditions,
				1824	e.g. type <code>T</code>, or use <code>IGNORE-ERRORS</code>.
				1825	Instead, let unknown conditions propagate to
				1826	the standard ultimate handler for processing.
				1827
				1828	</li>
				1829	<li>
				1830	There are a few places where handling all conditions is appropriate,
				1831	but they are rare.
				1832	The problem is that handling all conditions can mask program bugs.
				1833	If you <em>do</em> need to handle "all conditions",
				1834	you MUST handle only <code>ERROR</code>, <em>not</em> <code>T</code>
				1835	and not <code>SERIOUS-CONDITION</code>.
				1836	(This is notably because CCL's process shutdown
				1837	depends on being able to signal <code>process-reset</code>
				1838	and have it handled by CCL's handler,
				1839	so we must not interpose our own handler.)
				1840	</li>
				1841	<li>
				1842	<code>(error (make-condition 'foo-error ...))</code>
mark@chromium.org	8190c13	2013-03-21 16:03:26 +0000	[diff] [blame]	1843	is equivalent to <code>(error 'foo-error ...)</code> —
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	1844	code must use the shorter form.
				1845	</li>
				1846	<li>
				1847	Code should not signal conditions from inside the cleanup form of
				1848	<code>UNWIND-PROTECT</code>
				1849	(unless they are always handled inside the cleanup form),
tunes@google.com	13bb6e4	2012-10-15 20:57:01 +0000	[diff] [blame]	1850	or otherwise do non-local exits from cleanup handlers
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	1851	outside of the handler e.g. <code>INVOKE-RESTART</code>.
				1852	</li>
				1853	<li>
				1854	Do not clean up by resignaling.
				1855	If you do that, and the condition is not handled,
				1856	the stack trace will halt at the point of the resignal,
				1857	hiding the rest.
				1858	And the rest is the part we really care about!
				1859	<BAD_CODE_SNIPPET>
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	1860	;; Bad
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	1861	(handler-case
				1862	(catch 'ticket-at
				1863	(etd-process-blocks))
				1864	(error (c)
				1865	(reset-parser-values)
				1866	(error c)))
				1867	</BAD_CODE_SNIPPET>
				1868	<CODE_SNIPPET>
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	1869	;; Better
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	1870	(unwind-protect
				1871	(catch 'ticket-at
				1872	(etd-process-blocks))
				1873	(reset-parser-values))
				1874	</CODE_SNIPPET>
				1875	</li>
				1876	</ul>
				1877	</BODY>
				1878	</STYLEPOINT>
				1879	<STYLEPOINT title="Type Checking">
				1880	<SUMMARY>
				1881	If you know the type of something, you should make it explicit
				1882	in order to enable compile-time and run-time sanity-checking.
				1883	</SUMMARY>
				1884	<BODY>
				1885
				1886	<p>
				1887	If your function is using a special variable as an implicit argument,
				1888	it's good to put in a <code>CHECK-TYPE</code> for the special variable,
				1889	for two reasons:
				1890	to clue in the person reading the code
				1891	that this variable is being used implicitly as an argument,
				1892	and also to help detect bugs.
				1893	</p>
				1894
				1895	<p>
				1896	Using <code>(declare (type ...))</code>
				1897	is the least-desirable mechanism to use
				1898	because, as Scott McKay puts it:
				1899	</p>
				1900	<blockquote>
				1901	<p>
				1902	The fact is, <code>(declare (type ...))</code> does different things
				1903	depending on the compiler settings of speed, safety, etc.
				1904	In some compilers, when speed is greater than safety,
				1905	<code>(declare (type ...))</code> will tell the compiler
				1906	"please assume that these variables have these types"
				1907	<em>without</em> generating any type-checks.
				1908	That is, if some variable has the value <code>1432</code> in it,
				1909	and you declare it to be of type <code>string</code>,
				1910	the compiler might just go ahead and use it as though it's a string.
				1911	</p>
				1912	<p>
				1913	Moral: don't use <code>(declare (type ...))</code>
				1914	to declare the contract of any API functions,
				1915	it's not the right thing.
				1916	Sure, use it for "helper" functions, but not API functions.
				1917	</p>
				1918	</blockquote>
tunes@google.com	0c584cb	2012-10-11 17:06:57 +0000	[diff] [blame]	1919	<p>
tunes@google.com	8c4c5ce	2012-10-12 23:16:43 +0000	[diff] [blame]	1920	You should, of course, use appropriate declarations
tunes@google.com	0c584cb	2012-10-11 17:06:57 +0000	[diff] [blame]	1921	in internal low-level functions
				1922	where these declarations are used for optimization.
tunes@google.com	8c4c5ce	2012-10-12 23:16:43 +0000	[diff] [blame]	1923	When you do, however, see our recommendations for
				1924	<a href="#Unsafe_Operations">Unsafe Operations</a>.
tunes@google.com	0c584cb	2012-10-11 17:06:57 +0000	[diff] [blame]	1925	</p>
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	1926	</BODY>
				1927	</STYLEPOINT>
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	1928	<STYLEPOINT title="CLOS">
				1929	<SUMMARY>
				1930	Use CLOS appropriately.
				1931	</SUMMARY>
				1932	<BODY>
				1933	<p>
				1934	When a generic function is intended to be called from other
				1935	modules (other parts of the code), there should be an
				1936	explicit <code>DEFGENERIC</code> form,
				1937	with a <code>:DOCUMENTATION</code> string
				1938	explaining the generic contract of the function
				1939	(as opposed to its behavior for some specific class).
				1940	It's generally good to do explicit <code>DEFGENERIC</code> forms,
				1941	but for module entry points it is mandatory.
				1942	</p>
				1943	<p>
				1944	When the argument list of a generic function includes
				1945	<code>&KEY</code>,
				1946	the <code>DEFGENERIC</code> should always explicitly list
				1947	all of the keyword arguments that are acceptable,
				1948	and explain what they mean.
				1949	(Common Lisp does not require this, but it is good form,
				1950	and it may avoid spurious warnings on SBCL.)
				1951	</p>
				1952	<p>
				1953	You should avoid <code>SLOT-VALUE</code> and <code>WITH-SLOTS</code>,
				1954	unless you absolutely intend to circumvent
				1955	any sort of method combination that might be in effect for the slot.
				1956	Rare exceptions include <code>INITIALIZE-INSTANCE</code>
				1957	and <code>PRINT-OBJECT</code> methods and
tunes@google.com	0c584cb	2012-10-11 17:06:57 +0000	[diff] [blame]	1958	accessing normally hidden slots in the low-level implementation of
				1959	methods that provide user-visible abstractions.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	1960	Otherwise, you should use accessors,
				1961	<code>WITH-ACCESSORS</code>
				1962	</p>
				1963
				1964	<p>
				1965	Accessor names generally follow a convention of
				1966	<code><protocol-name>-<slot-name></code>,
tunes@google.com	0c584cb	2012-10-11 17:06:57 +0000	[diff] [blame]	1967	where a "protocol" in this case loosely indicates
				1968	a set of functions with well-defined behavior.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	1969	</p>
				1970	<p>
tunes@google.com	0c584cb	2012-10-11 17:06:57 +0000	[diff] [blame]	1971	No implication of a formal "protocol" concept is necessarily intended,
				1972	much less first-class "protocol" objects.
				1973	However, there may indeed be an abstract CLOS class
				1974	or an
Ackermann Yuriy	7969290	2016-04-01 21:41:34 +1300	[diff] [blame]	1975	<a href="https://common-lisp.net/~frideau/lil-ilc2012/lil-ilc2012.html">Interface-Passing Style</a> interface
tunes@google.com	0c584cb	2012-10-11 17:06:57 +0000	[diff] [blame]	1976	that embodies the protocol.
				1977	Further (sub)classes or (sub)interfaces may then implement
				1978	all or part of a protocol by defining
				1979	some methods for (generic) functions in the protocol,
				1980	including readers and writers.
				1981	</p>
				1982	<p>
				1983	For example, if there were a notional protocol called
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	1984	is <code>pnr</code> with accessors <code>pnr-segments</code>
				1985	and <code>pnr-passengers</code>, then
				1986	the classes <code>air-pnr</code>, <code>hotel-pnr</code> and
				1987	<code>car-pnr</code> could each reasonably implement
				1988	methods for <code>pnr-segments</code> and <code>pnr-passengers</code>
				1989	as accessors.
				1990	</p>
				1991	<p>
				1992	By default, an abstract base class name is used
				1993	as the notional protocol name, so accessor names default
				1994	to <code><class-name>-<slot-name></code>;
				1995	while such names are thus quite prevalent,
				1996	this form is neither required nor even preferred.
				1997	In general, it contributes to "symbol bloat",
				1998	and in many cases has led to a proliferation of "trampoline" methods.
				1999	</p>
				2000	<p>
				2001	Accessors named <code><slot-name>-of</code> should not be used.
				2002	</p>
				2003	<p>
				2004	Explicit <code>DEFGENERIC</code> forms should be used when there are
				2005	(or it is anticipated that there will be)
				2006	more than one <code>DEFMETHOD</code> for that generic function.
				2007	The reason is that the documentation for the generic function
				2008	explains the abstract contract for the function,
				2009	as opposed to explaining what an individual method does for
				2010	some specific class(es).
				2011	</p>
				2012	<p>
tunes@google.com	0c584cb	2012-10-11 17:06:57 +0000	[diff] [blame]	2013	You must not use generic functions where there is no notional protocol.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	2014	To put it more concretely,
				2015	if you have more than one generic function that specializes its Nth argument,
				2016	the specializing classes should all be descendants of a single class.
				2017	Generic functions must not be used for "overloading",
				2018	i.e. simply to use the same name for two entirely unrelated types.
				2019	</p>
				2020	<p>
				2021	More precisely, it's not really
				2022	whether they descend from a common superclass,
				2023	but whether they obey the same "protocol".
				2024	That is, the two classes should handle the same set of generic functions,
				2025	as if there were an explicit <code>DEFGENERIC</code> for each method.
				2026	</p>
				2027	<p>
				2028	Here's another way to put it.
				2029	Suppose you have two classes, A and B, and a generic function F.
				2030	There are two methods for F,
				2031	which dispatch on an argument being of types A and B.
				2032	Is it plausible that there might be a function call somewhere
				2033	in the program that calls F,
				2034	in which the argument might sometimes, at runtime,
				2035	be of class A and other times be of class B?
				2036	If not, you probably are overloading and
				2037	should not be using a single generic function.
				2038	</p>
				2039	<p>
				2040	We allow one exception to this rule:
				2041	it's OK to do overloading
				2042	if the corresponding argument "means" the same thing.
				2043	Typically one overloading allows an X object,
				2044	and the other allows the name of an X object,
				2045	which might be a symbol or something.
				2046	</p>
				2047	<p>
tunes@google.com	13bb6e4	2012-10-15 20:57:01 +0000	[diff] [blame]	2048	You must not use MOP "intercessory" operations at runtime.
				2049	You should not use MOP "intercessory" operations at compile-time.
				2050	At runtime, they are at worst a danger, at best a performance issue.
				2051	At compile-time, it is usually cleaner that
tunes@google.com	c55433c	2012-10-17 22:13:51 +0000	[diff] [blame]	2052	macros should set things up the right way in one pass
				2053	than have to require a second pass of fixups through intercession;
				2054	but sometimes, fixups are necessary to resolve forward references,
				2055	and intercession is allowed then.
tunes@google.com	13bb6e4	2012-10-15 20:57:01 +0000	[diff] [blame]	2056	MOP intercession is a great tool for interactive development,
tunes@google.com	c55433c	2012-10-17 22:13:51 +0000	[diff] [blame]	2057	and you may enjoy it while developping and debugging;
tunes@google.com	13bb6e4	2012-10-15 20:57:01 +0000	[diff] [blame]	2058	but you should not use it in normal applications.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	2059	</p>
				2060	<p>
				2061	If a class definition creates a method
				2062	as a <code>:READER</code>, <code>:WRITER</code>,
				2063	or <code>:ACCESSOR</code>,
				2064	do not redefine that method.
				2065	It's OK to add <code>:BEFORE</code>, <code>:AFTER</code>,
				2066	and <code>:AROUND</code> methods,
				2067	but don't override the primary method.
				2068	</p>
				2069	<p>
				2070	In methods with keyword arguments,
				2071	you must always use <code>&KEY</code>,
				2072	even if the method does not care about the values of any keys,
				2073	and you should never use <code>&ALLOW-OTHER-KEYS</code>.
				2074	As long as a keyword is accepted by any method of a generic function,
				2075	it's OK to use it in the generic function,
				2076	even if the other methods of the same generic function
				2077	don't mention it explicitly.
				2078	This is particularly important
				2079	for <code>INITIALIZE-INSTANCE</code> methods,
				2080	since if you did use <code>&ALLOW-OTHER-KEYS</code>,
				2081	it would disable error checking for misspelled or wrong keywords
				2082	in <code>MAKE-INSTANCE</code> calls!
				2083	</p>
				2084
				2085	<p>
				2086	A typical <code>PRINT-OBJECT</code> method might look like this:
				2087	</p>
				2088	<CODE_SNIPPET>
				2089	(defmethod print-object ((p person) stream)
tunes@google.com	13bb6e4	2012-10-15 20:57:01 +0000	[diff] [blame]	2090	(print-unprintable-object (p stream :type t :identity t)
				2091	(with-slots (first-name last-name) p
				2092	(safe-format stream "~a ~a" first-name last-name))))
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	2093	</CODE_SNIPPET>
				2094	</BODY>
				2095	</STYLEPOINT>
				2096	</CATEGORY>
				2097
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	2098	<CATEGORY title="Meta-language guidelines">
				2099	<STYLEPOINT title="Macros">
				2100	<SUMMARY>
				2101	Use macros when appropriate, which is often.
				2102	Define macros when appropriate, which is seldom.
				2103	</SUMMARY>
				2104	<BODY>
				2105	<p>
				2106	Macros bring syntactic abstraction, which is a wonderful thing.
				2107	It helps make your code clearer, by describing your intent
				2108	without getting bogged in implementation details
				2109	(indeed abstracting those details away).
				2110	It helps make your code more concise and more readable,
				2111	by eliminating both redundancy and irrelevant details.
				2112	But it comes at a cost to the reader,
				2113	which is learning a new syntactic concept for each macro.
				2114	And so it should not be abused.
				2115	</p>
				2116	<p>
				2117	The general conclusion is that there shouldn't be
				2118	any recognizable <em>design pattern</em>
				2119	in a good Common Lisp program.
				2120	The one and only pattern is: <em>use the language</em>,
				2121	which includes defining and using syntactic abstractions.
				2122	</p>
				2123	<p>
				2124	Existing macros must be used
				2125	whenever they make code clearer
				2126	by conveying intent in a more concise way,
				2127	which is often.
				2128	When a macro is available in your project
				2129	that expresses the concept you're using,
				2130	you must not write the expansion rather than use the macro.
				2131	</p>
				2132	<p>
				2133	New macros should be defined as appropriate,
				2134	which should be seldom,
				2135	for common macros have already been provided
				2136	by the language and its various libraries,
				2137	and your program typically only needs few new ones
				2138	relative to its size.
				2139	</p>
				2140	<p>
				2141	You should follow the OAOOM rule of thumb
				2142	for deciding when to create a new abstraction,
				2143	whether syntactic or not:
				2144	if a particular pattern is used more than twice,
				2145	it should probably be abstracted away.
				2146	A more refined rule to decide when to use abstraction
				2147	should take into account
				2148	the benefit in term of number of uses and gain at each use,
				2149	to the costs in term of having to get used to reading the code.
				2150	For syntactic abstractions, costs and benefits to the reader
				2151	is usually more important than costs and benefits to the writer,
				2152	because good code is usually written once
				2153	and read many times by many people
				2154	(including the same programmer
				2155	who has to maintain the program after having forgotten it).
				2156	Yet the cost to the writer of the macro
				2157	should also be taken into account;
				2158	however, in doing so it should rather be compared
				2159	to the cost of the programmer writing other code instead
				2160	that may have higher benefits.
				2161	</p>
				2162	<p>
				2163	Using Lisp macros properly requires taste.
				2164	Avoid writing complicated macros
				2165	unless the benefit clearly outweighs the cost.
				2166	It takes more effort for your fellow developers to learn your macro,
				2167	so you should only use a macro if the gain in expressiveness
				2168	is big enough to justify that cost.
				2169	As usual, feel free to consult your colleagues if you're not sure,
				2170	since without a lot of Lisp experience,
				2171	it can be hard to make this judgment.
				2172	</p>
				2173	<p>
				2174	You must never use a macro where a function will do.
				2175	That is, if the semantics of what you are writing
				2176	conforms to the semantics of a function,
				2177	then you must write it as a function rather than a macro.
				2178	</p>
				2179	<p>
				2180	You must not transform a function into a macro for performance reasons.
				2181	If profiling shows that you have a performance problem
				2182	with a specific function <code>FOO</code>,
				2183	document the need and profiling-results appropriately,
				2184	and
				2185	<code>(declaim (inline foo))</code>.
				2186	</p>
				2187
				2188	<p>
				2189	You can also use a compiler-macro
				2190	as a way to speed up function execution
				2191	by specifying a source-to-source transformation.
				2192	Beware that it interferes with tracing the optimized function.
				2193	</p>
				2194	<p>
				2195	When you write a macro-defining macro
				2196	(a macro that generates macros),
				2197	document and comment it particularly clearly,
mark@chromium.org	8190c13	2013-03-21 16:03:26 +0000	[diff] [blame]	2198	since these are harder to understand.
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	2199	</p>
				2200	<p>
				2201	You must not install new reader macros
				2202	without a consensus among the developers of your system.
				2203	Reader macros must not leak out of the system that uses them
				2204	to clients of that system or other systems used in the same project.
mark@chromium.org	5684bbc	2013-07-12 18:53:13 +0000	[diff] [blame]	2205	You must use software such as
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	2206	<code>cl-syntax</code> or <code>named-readtables</code>
				2207	to control how reader macros are used.
				2208	This clients who desire it may use the same reader macros as you do.
				2209	In any case, your system must be usable
				2210	even to clients who do not use these reader macros.
				2211	</p>
				2212	<p>
				2213	If your macro has a parameter that is a Lisp form
				2214	that will be evaluated when the expanded code is run,
				2215	you should name the parameter with the suffix <code>-form</code>.
				2216	This convention helps make it clearer to the macro's user
				2217	which parameters are Lisp forms to be evaluated, and which are not.
mark@chromium.org	5684bbc	2013-07-12 18:53:13 +0000	[diff] [blame]	2218	The common names <code>body</code> and <code>end</code> are
				2219	exceptions to this rule.
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	2220	</p>
				2221	<p>
				2222	You should follow the so-called <code>CALL-WITH</code> style when it applies.
				2223	This style is explained at length in
				2224	<a href="http://random-state.net/log/3390120648.html">http://random-state.net/log/3390120648.html</a>.
				2225	The general principle is that the macro is strictly limited to processing the syntax,
				2226	and as much of the semantics as possible is kept in normal functions.
				2227	Therefore, a macro <code>WITH-<em>FOO</em></code> is often limited to
				2228	generating a call to an auxiliary function
				2229	<code>CALL-WITH-<em>FOO</em></code>
				2230	with arguments deduced from the macro arguments.
				2231	Macro <code>&body</code> arguments are typically
				2232	wrapped into a lambda expression of which they become the body,
				2233	which is passed as one of the arguments of the auxiliary function.
				2234	</p>
				2235	<p>
				2236	The separation of syntactic and semantic concerns
				2237	is a general principle of style that applies
				2238	beyond the case of <code>WITH-</code> macros.
				2239	Its advantages are many.
				2240	By keeping semantics outside the macro,
				2241	the macro is made simpler, easier to get right, and less subject to change,
				2242	which makes it easier to develop and maintain.
mark@chromium.org	8190c13	2013-03-21 16:03:26 +0000	[diff] [blame]	2243	The semantics is written in a simpler language — one without staging —
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	2244	which also makes it easier to develop and maintain.
				2245	It becomes possible to debug and update the semantic function
				2246	without having to recompile all clients of the macro.
				2247	The semantic function appears in the stack trace
				2248	which also helps debug client functions.
				2249	The macro expansion is made shorter and
				2250	each expansion shares more code with other expansions,
				2251	which reduces memory pressure which in turn usually makes things faster.
				2252	It also makes sense to write the semantic functions first,
				2253	and write the macros last as syntactic sugar on top.
				2254	You should use this style unless the macro is used
				2255	in tight loops where performance matters;
				2256	and even then, see our rules regarding optimization.
				2257	</p>
				2258	<p>
				2259	Any functions (closures) created by the macro should be named,
				2260	which can be done using <code>FLET</code>.
				2261
				2262	This also allows you to declare the function to be of dynamic extent
mark@chromium.org	8190c13	2013-03-21 16:03:26 +0000	[diff] [blame]	2263	(if it is — and often it is; yet see below regarding
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	2264	<a href="#DYNAMIC-EXTENT">DYNAMIC-EXTENT</a>).
				2265	</p>
				2266	<p>
				2267	If a macro call contains a form,
				2268	and the macro expansion includes more than one copy of that form,
				2269	the form can be evaluated more than once,
				2270	and code it contains macro-expanded and compiled more than once.
				2271	If someone uses the macro and calls it
				2272	with a form that has side effects or that takes a long time to compute,
				2273	the behavior will be undesirable
				2274	(unless you're intentionally writing
				2275	a control structure such as a loop).
				2276	A convenient way to avoid this problem
				2277	is to evaluate the form only once,
				2278	and bind a (generated) variable to the result.
				2279	There is a very useful macro called <code>ALEXANDRIA:ONCE-ONLY</code>
				2280	that generates code to do this.
				2281	See also <code>ALEXANDRIA:WITH-GENSYMS</code>,
				2282	to make some temporary variables in the generated code.
tunes@google.com	13bb6e4	2012-10-15 20:57:01 +0000	[diff] [blame]	2283	Note that if you follow our <code>CALL-WITH</code> style,
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	2284	you typically expand the code only once, as either
				2285	an argument to the auxiliary function, or
				2286	the body of a lambda passed as argument to it;
				2287	you therefore avoid the above complexity.
				2288	</p>
				2289	<p>
				2290	When you write a macro with a body,
				2291	such as a <code>WITH-xxx</code> macro,
				2292	even if there aren't any parameters,
				2293	you should leave space for them anyway.
				2294	For example, if you invent <code>WITH-LIGHTS-ON</code>,
				2295	do not make the call to it look like
				2296	<code>(defmacro with-lights-on (&body b) ...)</code>.
				2297	Instead, do <code>(defmacro with-lights-on (() &body b) ...)</code>.
				2298	That way, if parameters are needed in the future,
				2299	you can add them without necessarily having to change
				2300	all the uses of the macro.
				2301	</p>
				2302	</BODY>
				2303	</STYLEPOINT>
				2304	<STYLEPOINT title="EVAL-WHEN">
				2305	<SUMMARY>
				2306	When using <code>EVAL-WHEN</code>, you should almost always use all of
				2307	<code>(:compile-toplevel :load-toplevel :execute)</code>.
				2308	</SUMMARY>
				2309	<BODY>
				2310	<p>
				2311	Lisp evaluation happens at several times,
				2312	some of them interleaved.
				2313	Be aware of them when writing macros.
Ackermann Yuriy	7969290	2016-04-01 21:41:34 +1300	[diff] [blame]	2314	<a href="https://fare.livejournal.com/146698.html">EVAL-WHEN considered harmful to your mental health</a>.
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	2315	</p>
				2316	<p>
				2317	In summary of the article linked above,
				2318	unless you're doing truly advanced macrology,
				2319	the only valid combination in an <code>EVAL-WHEN</code>
				2320	is to include all of
				2321	<code>(eval-when (:compile-toplevel :load-toplevel :execute) ...)</code>
				2322	</p>
				2323	<p>
				2324	You must use
				2325	<code>(eval-when (:compile-toplevel :load-toplevel :execute) ...)</code>
				2326	whenever you define functions, types, classes, constants, variables, etc.,
				2327	that are going to be used in macros.
				2328	</p>
				2329	<p>
				2330	It is usually an error to omit the <code>:execute</code>,
				2331	because it prevents <code>LOAD</code>ing the source rather than the fasl.
				2332	It is usually an error to omit the <code>:load-toplevel</code>
				2333	(except to modify e.g. readtables and compile-time settings),
				2334	because it prevents <code>LOAD</code>ing future files
				2335	or interactively compiling code
				2336	that depends on the effects that happen at compile-time,
				2337	unless the current file was <code>COMPILE-FILE</code>d
				2338	within the same Lisp session.
				2339	</p>
				2340	<p>
				2341	Regarding variables, note that because macros may or may not
				2342	be expanded in the same process that runs the expanded code,
				2343	you must not depend on compile-time and runtime effects
				2344	being either visible or invisible at the other time.
				2345	There are still valid uses of variables in macros:
				2346	</p>
				2347	<ul>
				2348	<li>
				2349	Some variables may hold dictionaries
				2350	for some new kind of definition and other meta-data.
				2351	If such meta-data is to be visible at runtime and/or in other files,
				2352	you must make sure that the macro expands into code that
				2353	will register the definitions to those meta-data structures
				2354	at load-time,
				2355	in addition to effecting the registration at compile-time.
				2356	Typically, your top-level definitions expand
				2357	to code that does the registration.
				2358	if your code doesn't expand at the top-level,
				2359	you can sometimes use <code>LOAD-TIME-VALUE</code> for good effect.
				2360	In extreme cases, you may have to use
				2361	<code>ASDF-FINALIZERS:EVAL-AT-TOPLEVEL</code>.
				2362	</li>
				2363	<li>
				2364	Some variables may hold temporary data
				2365	that is only used at compile-time in the same file,
				2366	and can be cleaned up at the end of the file's compilation.
				2367	Predefined such variables would include <code>readtable</code>
				2368	or compiler-internal variables holding
				2369	the current optimization settings.
				2370	You can often manage existing and new such variables using
				2371	the <code>:AROUND-COMPILE</code> hooks of <code>ASDF</code>.
				2372	</li>
				2373	</ul>
				2374	</BODY>
				2375	</STYLEPOINT>
				2376	<STYLEPOINT title="Read-time evaluation">
				2377	<SUMMARY>
				2378	You should use <code>#.</code> sparingly,
				2379	and you must avoid read-time side-effects.
				2380	</SUMMARY>
				2381	<BODY>
				2382	<p>
				2383	The <code>#.</code> standard read-macro
				2384	will read one object, evaluate the object, and
				2385	have the reader return the resulting value.
				2386	</p>
				2387	<p>
				2388	You must not use it where other idioms will do, such as
				2389	using <code>EVAL-WHEN</code> to evaluate side-effects at compile-time,
				2390	using a regular macro to return an expression computed at compile-time,
				2391	using <code>LOAD-TIME-VALUE</code> to compute it at load-time.
				2392	</p>
				2393	<p>
				2394	Read-time evaluation is often used as a quick way
				2395	to get something evaluated at compile time
				2396	(actually "read time" but it amounts to the same thing).
				2397	If you use this, the evaluation MUST NOT have any side effects
				2398	and MUST NOT depend on any variable global state.
				2399	The <code>#.</code> should be treated as a way
				2400	to force "constant-folding"
				2401	that a sufficiently-clever compiler
				2402	could have figure out all by itself,
				2403	when the compiler isn't sufficiently-clever
				2404	and the difference matters.
				2405	</p>
				2406	<p>
				2407	Another use of <code>#.</code> is to expand the equivalent of macros
				2408	in places that are neither expressions nor (quasi)quotations,
				2409	such as lambda-lists. However, if you find yourself using it a lot,
				2410	it might be time to instead define macros to replace your consumers
				2411	of lambda-lists with something that recognizes an extension.
				2412	</p>
				2413	<p>
				2414	Whenever you are going to use <code>#.</code>,
				2415	you should consider using <code>DEFCONSTANT</code> and its variants,
				2416	possibly in an <code>EVAL-WHEN</code>,
				2417	to give the value a name explaining what it means.
				2418	</p>
				2419	</BODY>
				2420	</STYLEPOINT>
				2421	<STYLEPOINT title="EVAL">
				2422	<SUMMARY>
				2423	You must not use <code>EVAL</code> at runtime.
				2424	</SUMMARY>
				2425	<BODY>
				2426	<p>
				2427	Places where it is actually appropriate to use <code>EVAL</code>
				2428	are so few and far between that you must consult with your reviewers;
				2429	it's easily misused.
				2430	</p>
				2431	<p>
				2432	If your code manipulates symbols at runtime
				2433	and needs to get the value of a symbol,
				2434	use <code>SYMBOL-VALUE</code>, not <code>EVAL</code>.
				2435	</p>
				2436	<p>
				2437	Often, what you really need is to write a macro,
				2438	not to use <code>EVAL</code>.
				2439	</p>
				2440	<p>
				2441	You may be tempted to use <code>EVAL</code> as a shortcut
				2442	to evaluating expressions in a safe subset of the language.
				2443	But it often requires more scrutiny to properly check and sanitize
				2444	all possible inputs to such use of <code>EVAL</code>
				2445	than to build a special-purpose evaluator.
				2446	You must not use <code>EVAL</code> in this way at runtime.
				2447	</p>
				2448	<p>
				2449	Places where it is OK to use <code>EVAL</code> are:
				2450	</p>
				2451	<ul>
				2452	<li>
tunes@google.com	d6c053f	2013-09-19 17:26:22 +0000	[diff] [blame]	2453	The implementation of an interactive development tool.
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	2454	</li>
				2455	<li>
				2456	The build infrastructure.
				2457	</li>
				2458	<li>
				2459	Backdoors that are part of testing frameworks.
				2460	(You MUST NOT have such backdoors in production code.)
				2461	</li>
				2462	<li>
				2463	Macros that fold constants at compile-time.
				2464	</li>
				2465	<li>
				2466	Macros that register definitions to meta-data structures;
				2467	the registration form is sometimes evaluated at compile-time
				2468	as well as included in the macro-expansion,
				2469	so it is immediately available to other macros.
				2470	</li>
				2471	</ul>
				2472	<p>
				2473	Note that in the latter case,
				2474	if the macro isn't going to be used at the top-level,
				2475	it might not be possible to make these definitions available
				2476	as part of the expansion.
				2477	The same phenomenon may happen in a <code>DEFTYPE</code> expansion,
				2478	or in helper functions used by macros.
				2479	In these cases, you may actually have to use
				2480	<code>ASDF-FINALIZERS:EVAL-AT-TOPLEVEL</code> in your macro.
				2481	It will not only <code>EVAL</code> your definitions
				2482	at macro-expansion time for immediate availability,
				2483	it will also save the form aside, for inclusion in a
				2484	<code>(ASDF-FINALIZERS:FINAL-FORMS)</code>
				2485	that you need to include at the end of the file being compiled
				2486	(or before the form is needed).
				2487	This way, the side-effects are present when loading the fasl
				2488	without having compiled it as well as while compiling it;
				2489	in either case, the form is made available at load-time.
				2490	<code>ASDF-FINALIZERS</code> ensures that the form is present,
				2491	by throwing an error if you omit it.
				2492	</p>
				2493	</BODY>
				2494	</STYLEPOINT>
tunes@google.com	13bb6e4	2012-10-15 20:57:01 +0000	[diff] [blame]	2495	<STYLEPOINT title="INTERN and UNINTERN">
				2496	<SUMMARY>
				2497	You must not use <code>INTERN</code> or <code>UNINTERN</code> at runtime.
				2498	</SUMMARY>
				2499	<BODY>
				2500	<p>
				2501	You must not use <code>INTERN</code> at runtime.
				2502	Not only does it cons,
				2503	it either creates a permanent symbol that won't be collected
				2504	or gives access to internal symbols.
				2505	This creates opportunities for memory leaks, denial of service attacks,
				2506	unauthorized access to internals, clashes with other symbols.
				2507	</p>
				2508	<p>
				2509	You must not <code>INTERN</code> a string
				2510	just to compare it to a keyword;
				2511	use <code>STRING=</code> or <code>STRING-EQUAL</code>.
				2512	</p>
				2513	<BAD_CODE_SNIPPET>
				2514	(member (intern str :keyword) $keys) ; Bad
				2515	</BAD_CODE_SNIPPET>
				2516	<CODE_SNIPPET>
				2517	(member str $keys :test #'string-equal) ; Better
				2518	</CODE_SNIPPET>
				2519	<p>
				2520	You must not use <code>UNINTERN</code> at runtime.
				2521	It can break code that relies on dynamic binding.
				2522	It makes things harder to debug.
				2523	You must not dynamically intern any new symbol,
				2524	and therefore you need not dynamically unintern anything.
				2525	</p>
				2526	<p>
				2527	You may of course use <code>INTERN</code> at compile-time,
				2528	in the implementation of some macros.
				2529	Even so, it is usually more appropriate
				2530	to use abstractions on top of it, such as
				2531	<code>ALEXANDRIA:SYMBOLICATE</code> or
				2532	<code>ALEXANDRIA:FORMAT-SYMBOL</code>
				2533	to create the symbols you need.
				2534	</p>
				2535
				2536	</BODY>
				2537	</STYLEPOINT>
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	2538	</CATEGORY>
				2539
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	2540	<CATEGORY title="Data Representation">
				2541	<STYLEPOINT title="NIL: empty-list, false and I Don't Know">
				2542	<SUMMARY>
tunes@google.com	13bb6e4	2012-10-15 20:57:01 +0000	[diff] [blame]	2543	Appropriately use or avoid using <code>NIL</code>.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	2544	</SUMMARY>
				2545	<BODY>
				2546	<p>
				2547	<code>NIL</code> can have several different interpretations:
				2548	</p>
				2549	<ul>
				2550	<li>
				2551	"False."
				2552	In this case, use <code>NIL</code>.
				2553	You should test for false <code>NIL</code>
				2554	using the operator <code>NOT</code> or
				2555	using the predicate function <code>NULL</code>.
				2556	</li>
				2557	<li>
				2558	"Empty-list."
				2559	In this case, use <code>'()</code>.
				2560	(Be careful about quoting the empty-list when calling macros.)
				2561	You should use <code>ENDP</code> to test for the empty list
				2562	when the argument is known to be a proper list,
				2563	or with <code>NULL</code> otherwise.
				2564	</li>
				2565	<li>
				2566	A statement about some value being unspecified.
				2567	In this case, you may use <code>NIL</code>
				2568	if there is no risk of ambiguity anywhere in your code;
				2569	otherwise you should use an explicit, descriptive symbol.
				2570	</li>
				2571	<li>
				2572	A statement about some value being known not to exist.
				2573	In this case, you should use an explicit, descriptive symbol
				2574	instead of <code>NIL</code>.
				2575	</li>
				2576	</ul>
				2577	<p>
				2578	You must not introduce ambiguity in your data representations
				2579	that will cause headaches for whoever has to debug code.
				2580	If there is any risk of ambiguity,
				2581	you should use an explicit, descriptive symbol or keyword
				2582	for each case,
				2583	instead of using <code>NIL</code> for either.
				2584	If you do use <code>NIL</code>,
				2585	you must make sure that the distinction is well documented.
				2586	</p>
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	2587	<p>
				2588	In many contexts,
				2589	instead of representing "I don't know" as a particular value,
				2590	you should instead use multiple values,
				2591	one for the value that is known if any,
				2592	and one to denote whether the value was known or found.
				2593	</p>
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	2594
				2595	<p>
				2596	When working with database classes, keep in mind that
				2597	<code>NIL</code> need not always map to <code>'NULL'</code>
				2598	(and vice-versa)!
				2599	The needs of the database may differ from the needs of the Lisp.
				2600	</p>
				2601	</BODY>
				2602	</STYLEPOINT>
				2603	<STYLEPOINT title="Do not abuse lists">
				2604	<SUMMARY>
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	2605	You must select proper data representation.
				2606	You must not abuse the <code>LIST</code> data structure.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	2607	</SUMMARY>
				2608	<BODY>
				2609	<p>
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	2610	Even though back in 1958, LISP was short for "LISt Processing",
				2611	its successor Common Lisp has been a modern programming language
				2612	with modern data structures since the 1980s.
				2613	You must use the proper data structures in your programs.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	2614	</p>
				2615	<p>
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	2616	You must not abuse the builtin (single-linked) <code>LIST</code>
				2617	data structure where it is not appropriate,
				2618	even though Common Lisp makes it especially easy to use it.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	2619	</p>
				2620	<p>
				2621	You must only use lists
				2622	when their performance characteristics
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	2623	is appropriate for the algorithm at hand:
				2624	sequential iteration over the entire contents of the list.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	2625	</p>
				2626	<p>
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	2627	An exception where it is appropriate to use lists
				2628	is when it is known in advance
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	2629	that the size of the list will remain very short
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	2630	(say, less than 16 elements).
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	2631	</p>
				2632	<p>
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	2633	List data structures are often (but not always)
				2634	appropriate for macros and functions used by macros at compile-time:
				2635	indeed, not only is source code passed as lists in Common Lisp,
				2636	but the macro-expansion and compilation processes
				2637	will typically walk over the entire source code, sequentially, once.
				2638	(Note that advanced macro systems don't directly use lists, but instead
				2639	use abstract syntax objects that track source code location and scope;
				2640	however there is no such advanced macro system
				2641	in Common Lisp at this time.)
				2642	</p>
				2643	<p>
				2644	Another exception where it is appropriate to use lists is
				2645	for introducing literal constants
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	2646	that will be transformed into more appropriate data structures
				2647	at compile-time or load-time.
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	2648	It is a good to have a function with a relatively short name
				2649	to build your program's data structures from such literals.
				2650	</p>
				2651	<p>
				2652	In the many cases when lists are not the appropriate data structure,
				2653	various libraries such as
				2654	<a href="http://cliki.net/cl-containers">cl-containers</a> or
				2655	<a href="http://cliki.net/lisp-interface-library">lisp-interface-library</a>
				2656	provide plenty of different data structures
				2657	that should fulfill all the basic needs of your programs.
				2658	If the existing libraries are not satisfactory, see above about
				2659	<a href="#Using_Libraries">Using Libraries</a> and
				2660	<a href="#Open-Sourcing_Code">Open-Sourcing Code</a>.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	2661	</p>
				2662	</BODY>
				2663	</STYLEPOINT>
				2664	<STYLEPOINT title="Lists vs. structures vs. multiple values">
				2665	<SUMMARY>
				2666	You should use the appropriate representation for product types.
				2667	</SUMMARY>
				2668	<BODY>
				2669	<p>
				2670	You should avoid using a list as anything
				2671	besides a container of elements of like type.
				2672	You must not use a list as method of passing
				2673	multiple separate values of different types
				2674	in and out of function calls.
				2675	Sometimes it is convenient to use a list
				2676	as a little ad hoc structure,
				2677	i.e. "the first element of the list is a FOO, and the second is a BAR",
				2678	but this should be used minimally
				2679	since it gets harder to remember the little convention.
				2680	You must only use a list that way
				2681	when destructuring the list of arguments from a function,
				2682	or creating a list of arguments
				2683	to which to <code>APPLY</code> a function.
				2684	</p>
				2685	<p>
				2686	The proper way to pass around an object
				2687	comprising several values of heterogeneous types
				2688	is to use a structure as defined by <code>DEFSTRUCT</code>
				2689	or <code>DEFCLASS</code>.
				2690	</p>
				2691	<p>
				2692	You should use multiple values only
				2693	when function returns a small number of values
				2694	that are meant to be destructured immediately by the caller,
				2695	rather than passed together as arguments to further functions.
				2696	</p>
				2697	<p>
				2698	You should not return a condition object
				2699	as one of a set of multiple values.
				2700	Instead, you should signal the condition to denote an unusual outcome.
				2701	</p>
				2702	<p>
				2703	You should signal a condition to denote an unusual outcome,
				2704	rather than relying on a special return type.
				2705	</p>
				2706	</BODY>
				2707	</STYLEPOINT>
				2708	<STYLEPOINT title="Lists vs. Pairs">
				2709	<SUMMARY>
				2710	Use the appropriate functions when manipulating lists.
				2711	</SUMMARY>
				2712	<BODY>
				2713	<p>
				2714	Use <code>FIRST</code> to access the first element of a list,
				2715	<code>SECOND</code> to access the second element, etc.
				2716	Use <code>REST</code> to access the tail of a list.
				2717	Use <code>ENDP</code> to test for the end of the list.
				2718	</p>
				2719	<p>
				2720	Use <code>CAR</code> and <code>CDR</code>
				2721	when the cons cell is not being used to implement a proper list
				2722	and is instead being treated as a pair of more general objects.
				2723	Use <code>NULL</code> to test for <code>NIL</code> in this context.
				2724	</p>
				2725	<p>
				2726	The latter case should be rare outside of alists,
				2727	since you should be using structures and classes where they apply,
				2728	and data structure libraries when you want trees.
				2729	</p>
				2730	<p>
				2731	Exceptionally, you may use <code>CDADR</code> and other variants
				2732	on lists when manually destructuring them,
				2733	instead of using a combination of several list accessor functions.
				2734	In this context, using <code>CAR</code> and <code>CDR</code>
				2735	instead of <code>FIRST</code> and <code>REST</code> also makes sense.
tunes@google.com	0c584cb	2012-10-11 17:06:57 +0000	[diff] [blame]	2736	However, keep in mind that it might be more appropriate in such cases
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	2737	to use higher-level constructs such as
mark@chromium.org	7b24563	2013-09-25 21:16:00 +0000	[diff] [blame]	2738	<code>DESTRUCTURING-BIND</code> or <code>OPTIMA:MATCH</code>.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	2739	</p>
				2740	</BODY>
				2741	</STYLEPOINT>
				2742	<STYLEPOINT title="Lists vs. Arrays">
				2743	<SUMMARY>
				2744	You should use arrays rather than lists where random access matters.
				2745	</SUMMARY>
				2746	<BODY>
				2747	<p>
				2748	<code>ELT</code> has <i>O(n)</i> behavior when used on lists.
				2749	If you are to use random element access on an object,
				2750	use arrays and <code>AREF</code> instead.
				2751	</p>
				2752	<p>
				2753	The exception is for code outside the critical path
				2754	where the list is known to be small anyway.
				2755	</p>
				2756	</BODY>
				2757	</STYLEPOINT>
				2758	<STYLEPOINT title="Lists vs. Sets">
				2759	<SUMMARY>
				2760	You should only use lists as sets for very small lists.
				2761	</SUMMARY>
				2762	<BODY>
				2763	<p>
				2764	Using lists as representations of sets is a bad idea
				2765	unless you know the lists will be small,
				2766	for accessors are <i>O(n)</i> instead of <i>O(log n)</i>.
				2767	For arbitrary big sets, use balanced binary trees,
				2768	for instance using <code>lisp-interface-library</code>.
				2769	</p>
				2770	<p>
				2771	If you still use lists as sets,
				2772	you should not <code>UNION</code> lists just to search them.
				2773	</p>
				2774	<BAD_CODE_SNIPPET>
				2775	(member foo (union list-1 list-2)) ; Bad
				2776	</BAD_CODE_SNIPPET>
				2777	<CODE_SNIPPET>
				2778	(or (member foo list-1) (member foo list-2)) ; Better
				2779	</CODE_SNIPPET>
				2780	<p>
				2781	Indeed, <code>UNION</code> not only conses unnecessarily,
				2782	but it can be <i>O(n^2)</i> on some implementations,
				2783	and is rather slow even when it's <i>O(n)</i>.
				2784	</p>
				2785	</BODY>
				2786	</STYLEPOINT>
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	2787	</CATEGORY>
				2788
				2789	<CATEGORY title="Proper Forms">
				2790	<p>
				2791	You must follow the proper usage regarding
				2792	well-known functions, macros and special forms.
				2793	</p>
				2794	<STYLEPOINT title="Defining Constants">
				2795	<SUMMARY>
				2796	You must use proper defining forms for constant values.
				2797	</SUMMARY>
				2798	<BODY>
				2799	<p>
				2800	The Lisp system we primarily use, SBCL, is very picky and
				2801	signals a condition whenever a constant is redefined to a value not
				2802	<code>EQL</code> to its previous setting.
				2803	You must not use <code>DEFCONSTANT</code>
				2804	when defining variables that are not
				2805	numbers, characters, or symbols (including booleans and keywords).
				2806	Instead, consistently use whichever alternative
				2807	is recommended for your project.
				2808	</p>
				2809	<BAD_CODE_SNIPPET>
				2810	;; Bad
Ackermann Yuriy	7969290	2016-04-01 21:41:34 +1300	[diff] [blame]	2811	(defconstant +google-url+ "https://www.google.com/")
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	2812	(defconstant +valid-colors+ '(red green blue))
				2813	</BAD_CODE_SNIPPET>
				2814
				2815
				2816
				2817
				2818	<p>
				2819	Open-Source libraries may use
				2820	<code>ALEXANDRIA:DEFINE-CONSTANT</code>
				2821	for constants other than numbers, characters and symbols
				2822	(including booleans and keywords).
				2823	You may use the <code>:TEST</code> keyword argument
				2824	to specify an equality predicate.
				2825	</p>
				2826	<CODE_SNIPPET>
				2827	;; Better, for Open-Source code:
Ackermann Yuriy	7969290	2016-04-01 21:41:34 +1300	[diff] [blame]	2828	(define-constant +google-url+ "https://www.google.com/" :test #'string=)
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	2829	(define-constant +valid-colors+ '(red green blue))
				2830	</CODE_SNIPPET>
tunes@google.com	0c584cb	2012-10-11 17:06:57 +0000	[diff] [blame]	2831	<p>
				2832	Note that with optimizing implementations, such as SBCL or CMUCL,
				2833	defining constants this way precludes any later redefinition
				2834	short of <code>UNINTERN</code>ing the symbol
				2835	and recompiling all its clients.
				2836	This may make it "interesting" to debug things at the REPL
				2837	or to deploy live code upgrades.
				2838	If there is a chance that your "constants" are not going to be constant
				2839	over the lifetime of your server processes
				2840	after taking into consideration scheduled and unscheduled code patches,
				2841	you should consider using
				2842	<code>DEFPARAMETER</code> or <code>DEFVAR</code> instead,
				2843	or possibly a variant of <code>DEFINE-CONSTANT</code>
				2844	that builds upon some future library implementing global lexicals
				2845	rather than <code>DEFCONSTANT</code>.
				2846	You may keep the <code>+plus+</code> convention in these cases
				2847	to document the intent of the parameter as a constant.
				2848	</p>
				2849	<p>
				2850	Also note that <code>LOAD-TIME-VALUE</code> may help you
				2851	avoid the need for defined constants.
				2852	</p>
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	2853	</BODY>
				2854	</STYLEPOINT>
				2855	<STYLEPOINT title="Defining Functions">
				2856	<SUMMARY>
				2857	You should make proper use of
mark@chromium.org	5684bbc	2013-07-12 18:53:13 +0000	[diff] [blame]	2858	<code>&OPTIONAL</code> and
				2859	<code>&KEY</code> arguments.
				2860	You should not use <code>&AUX</code> arguments.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	2861	</SUMMARY>
				2862	<BODY>
				2863	<p>
				2864	You should avoid using <code>&ALLOW-OTHER-KEYS</code>,
				2865	since it blurs the contract of a function.
				2866	Almost any real function (generic or not) allows a certain
				2867	fixed set of keywords, as far as its caller is concerned,
				2868	and those are part of its contract.
				2869	If you are implementing a method of a generic function,
				2870	and it does not need to know
				2871	the values of some of the keyword arguments,
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	2872	you should explicitly <code>(DECLARE (IGNORE ...))</code>
				2873	all the arguments that you are not using.
				2874	You must not use <code>&ALLOW-OTHER-KEYS</code>
				2875	unless you explicitly want to disable checking of allowed keys
				2876	for all methods when invoking the generic function on arguments
				2877	that match this particular method.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	2878	Note that the contract of a generic function belongs in
				2879	the <code>DEFGENERIC</code>, not in the <code>DEFMETHOD</code>
				2880	which is basically an "implementation detail" of the generic function
				2881	as far as the caller of the generic is concerned.
				2882	</p>
				2883	<p>
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	2884	A case where <code>&ALLOW-OTHER-KEYS</code> is appropriate
				2885	is when you write a wrapper function to other some other functions
				2886	that may vary (within the computation or during development),
				2887	and pass around a plist as a <code>&REST</code> argument.
				2888	</p>
				2889	<p>
mark@chromium.org	5684bbc	2013-07-12 18:53:13 +0000	[diff] [blame]	2890	You should avoid using <code>&AUX</code> arguments.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	2891	</p>
				2892	<p>
				2893	You should avoid having both <code>&OPTIONAL</code>
				2894	and <code>&KEY</code> arguments,
				2895	unless it never makes sense to specify keyword arguments
				2896	when the optional arguments are not all specified.
				2897	You must not have non-<code>NIL</code> defaults
				2898	to your <code>&OPTIONAL</code> arguments
				2899	when your function has both <code>&OPTIONAL</code>
				2900	and <code>&KEY</code> arguments.
				2901	</p>
				2902	<p>
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	2903	For maximum portability of a library, it is good form
				2904	that <code>DEFMETHOD</code> definitions should
				2905	<code>(DECLARE (IGNORABLE ...))</code>
				2906	all the required arguments that they are not using.
				2907	Indeed, some implementations will issue a warning
				2908	if you <code>(DECLARE (IGNORE ...))</code> those arguments,
				2909	whereas other implementations will issue a warning
				2910	if you fail to <code>(DECLARE (IGNORE ...))</code> them.
				2911	<code>(DECLARE (IGNORABLE ...))</code> works on all implementations.
				2912	</p>
				2913	<p>
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	2914	You should avoid excessive nesting of binding forms inside a function.
				2915	If your function ends up with massive nesting,
				2916	you should probably break it up into several functions or macros.
				2917	If it is really a single conceptual unit,
				2918	consider using a macro such as <code>FARE-UTILS:NEST</code>
				2919	to at least reduce the amount of indentation required.
				2920	It is bad form to use <code>NEST</code> in typical short functions
				2921	with 4 or fewer levels of nesting,
				2922	but also bad form not to use it in the exceptional long functions
				2923	with 10 or more levels of nesting.
				2924	Use your judgment and consult your reviewers.
				2925	</p>
				2926
				2927	</BODY>
				2928	</STYLEPOINT>
				2929	<STYLEPOINT title="Conditional Expressions">
				2930	<SUMMARY>
				2931	Use the appropriate conditional form.
				2932	</SUMMARY>
				2933	<BODY>
				2934	<p>
				2935	Use <code>WHEN</code> and <code>UNLESS</code>
				2936	when there is only one alternative.
				2937	Use <code>IF</code> when there are two alternatives
				2938	and <code>COND</code> when there are several.
				2939	</p>
				2940	<p>
				2941	However, don't use <code>PROGN</code> for an <code>IF</code> clause
mark@chromium.org	8190c13	2013-03-21 16:03:26 +0000	[diff] [blame]	2942	— use <code>COND</code>, <code>WHEN</code>, or <code>UNLESS</code>.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	2943	</p>
				2944	<p>
				2945	Note that in Common Lisp,
				2946	<code>WHEN</code> and <code>UNLESS</code> return <code>NIL</code>
tunes@google.com	13bb6e4	2012-10-15 20:57:01 +0000	[diff] [blame]	2947	when the condition is not met.
				2948	You may take advantage of it.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	2949	Nevertheless, you may use an <code>IF</code>
				2950	to explicitly return <code>NIL</code>
				2951	if you have a specific reason to insist on the return value.
tunes@google.com	c55433c	2012-10-17 22:13:51 +0000	[diff] [blame]	2952	You may similarly include a fall-through clause <code>(t nil)</code>
tunes@google.com	13bb6e4	2012-10-15 20:57:01 +0000	[diff] [blame]	2953	as the last in your <cond>COND</cond>,
tunes@google.com	c55433c	2012-10-17 22:13:51 +0000	[diff] [blame]	2954	or <code>(otherwise nil)</code> as the last in your <cond>CASE</cond>,
				2955	to insist on the fact that the value returned by the conditional matters
				2956	and that such a case is going to be used.
tunes@google.com	13bb6e4	2012-10-15 20:57:01 +0000	[diff] [blame]	2957	You should omit the fall-through clause
				2958	when the conditional is used for side-effects.
				2959	</p>
				2960	<p>
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	2961	You should prefer <code>AND</code> and <code>OR</code>
				2962	when it leads to more concise code than using
				2963	<code>IF</code>, <code>COND</code>,
				2964	<code>WHEN</code> or <code>UNLESS</code>,
				2965	and there are no side-effects involved.
				2966	You may also use an <code>ERROR</code>
				2967	as a side-effect in the final clause of an <code>OR</code>.
				2968	</p>
				2969	<p>
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	2970	You should only use <code>CASE</code> and <code>ECASE</code>
tunes@google.com	8c4c5ce	2012-10-12 23:16:43 +0000	[diff] [blame]	2971	to compare numbers, characters or symbols
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	2972	(including booleans and keywords).
				2973	Indeed, <code>CASE</code> uses <code>EQL</code> for comparisons,
tunes@google.com	8c4c5ce	2012-10-12 23:16:43 +0000	[diff] [blame]	2974	so strings, pathnames and structures may not compare the way you expect,
				2975	and <code>1</code> will differ from <code>1.0</code>.
				2976	</p>
				2977	<p>
				2978	You should use <code>ECASE</code> and <code>ETYPECASE</code>
				2979	in preference to <code>CASE</code> and <code>TYPECASE</code>.
				2980	It is better to catch erroneous values early.
				2981	</p>
				2982	<p>
				2983	You should not use <code>CCASE</code> or <code>CTYPECASE</code> at all.
				2984	At least, you should not use them in server processes,
				2985	unless you have quite robust error handling infrastructure
				2986	and make sure not to leak sensitive data this way.
				2987	These are meant for interactive use,
				2988	and can cause interesting damage
tunes@google.com	1407ba7	2012-11-08 04:31:59 +0000	[diff] [blame]	2989	if they cause data or control to leak to attackers.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	2990	</p>
				2991	<p>
				2992	You must not use gratuitous single quotes in <code>CASE</code> forms.
				2993	This is a common error:
				2994	</p>
				2995	<BAD_CODE_SNIPPET>
tunes@google.com	8c4c5ce	2012-10-12 23:16:43 +0000	[diff] [blame]	2996	(case x ; Bad: silently returns NIL on mismatch
				2997	('bar :bar) ; Bad: catches QUOTE
				2998	('baz :baz)) ; Bad: also would catch QUOTE
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	2999	</BAD_CODE_SNIPPET>
tunes@google.com	8c4c5ce	2012-10-12 23:16:43 +0000	[diff] [blame]	3000	<CODE_SNIPPET>
				3001	(ecase x ; Better: will error on mismatch
				3002	((bar) :bar) ; Better: won't match QUOTE
				3003	((baz) :baz)) ; Better: same reason
				3004	</CODE_SNIPPET>
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	3005	<p>
				3006	<code>'BAR</code> there is <code>(QUOTE BAR)</code>,
				3007	meaning this leg of the case will be executed
				3008	if <code>X</code> is <code>QUOTE</code>...
				3009	and ditto for the second leg
				3010	(though <code>QUOTE</code> will be caught by the first clause).
				3011	This is unlikely to be what you really want.
				3012	</p>
				3013	<p>
				3014	In <code>CASE</code> forms,
				3015	you must use <code>otherwise</code> instead of <code>t</code>
				3016	when you mean "execute this clause if the others fail".
tunes@google.com	8c4c5ce	2012-10-12 23:16:43 +0000	[diff] [blame]	3017	You must use <code>((t) ...)</code>
				3018	when you mean "match the symbol T" rather than "match anything".
				3019	You must also use <code>((nil) ...)</code>
				3020	when you mean "match the symbol NIL" rather than "match nothing".
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	3021	</p>
				3022	<p>
tunes@google.com	8c4c5ce	2012-10-12 23:16:43 +0000	[diff] [blame]	3023	Therefore, if you want to map booleans <code>NIL</code> and <code>T</code>
				3024	to respective symbols <code>:BAR</code> and <code>:QUUX</code>,
				3025	you should avoid the former way and do it the latter way:
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	3026	</p>
tunes@google.com	8c4c5ce	2012-10-12 23:16:43 +0000	[diff] [blame]	3027	<BAD_CODE_SNIPPET>
				3028	(ecase x ; Bad: has no actual error case!
				3029	(nil :bar)) ; Bad: matches nothing
				3030	(t :quux)) ; Bad: matches anything
				3031	</BAD_CODE_SNIPPET>
				3032	<CODE_SNIPPET>
				3033	(ecase x ; Better: will actually catch non-booleans
				3034	((nil) :bar)) ; Better: matches NIL
				3035	((t) :quux)) ; Better: matches T
				3036	</CODE_SNIPPET>
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	3037	</BODY>
				3038	</STYLEPOINT>
				3039	<STYLEPOINT title="Identity, Equality and Comparisons">
				3040	<SUMMARY>
				3041	You should the appropriate predicates when comparing objects.
				3042	</SUMMARY>
				3043	<BODY>
				3044	<p>
				3045	Lisp provides four general equality predicates:
				3046	<code>EQ</code>, <code>EQL</code>, <code>EQUAL</code>,
				3047	and <code>EQUALP</code>,
				3048	which subtly vary in semantics.
				3049	Additionally, Lisp provides the type-specific predicates
				3050	<code>=</code>, <code>CHAR=</code>, <code>CHAR-EQUAL</code>,
				3051	<code>STRING=</code>, and <code>STRING-EQUAL</code>.
				3052	Know the distinction!
				3053	</p>
				3054	<p>
				3055	You should use <code>EQL</code> to compare objects and symbols
				3056	for <em>identity</em>.
				3057	</p>
				3058	<p>
				3059	You must not use <code>EQ</code> to compare numbers or characters.
				3060	Two numbers or characters that are <code>EQL</code>
				3061	are not required by Common Lisp to be <code>EQ</code>.
				3062	</p>
				3063	<p>
				3064	When choosing between <code>EQ</code> and <code>EQL</code>,
				3065	you should use <code>EQL</code> unless you are writing
				3066	performance-critical low-level code.
				3067	<code>EQL</code> reduces the opportunity
				3068	for a class of embarrassing errors
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	3069	(i.e. if numbers or characters are ever compared).
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	3070	There may a tiny performance cost relative to <code>EQ</code>,
				3071	although under SBCL, it often compiles away entirely.
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	3072	<code>EQ</code> is equivalent to <code>EQL</code> and type declarations,
				3073	and use of it for optimization should be treated just like
				3074	any such <a href="#Unsafe_Operations">unsafe operations</a>.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	3075	</p>
				3076	<p>
				3077	You should use <code>CHAR=</code>
				3078	for case-dependent character comparisons,
				3079	and <code>CHAR-EQUAL</code> for case-ignoring character comparisons.
				3080	</p>
				3081	<p>
				3082	You should use <code>STRING=</code>
				3083	for case-dependent string comparisons,
				3084	and <code>STRING-EQUAL</code> for case-ignoring string comparisons.
				3085	</p>
				3086	<p>
				3087	A common mistake when using <code>SEARCH</code> on strings
				3088	is to provide <code>STRING=</code> or <code>STRING-EQUAL</code>
				3089	as the <code>:TEST</code> function.
				3090	The <code>:TEST</code> function
				3091	is given two sequence elements to compare.
				3092	If the sequences are strings,
				3093	the <code>:TEST</code> function is called on two characters,
				3094	so the correct tests are <code>CHAR=</code> or <code>CHAR-EQUAL</code>.
				3095	If you use <code>STRING=</code> or <code>STRING-EQUAL</code>,
				3096	the result is what you expect,
				3097	but in some Lisp implementations it's much slower.
				3098	CCL (at least as of 8/2008)
				3099	creates a one-character string upon each comparison, for example,
				3100	which is very expensive.
				3101	</p>
				3102	<p>
				3103	Also, you should use <code>:START</code> and <code>:END</code> arguments
				3104	to <code>STRING=</code> or <code>STRING-EQUAL</code>
				3105	instead of using <code>SUBSEQ</code>;
				3106	e.g. <code>(string-equal (subseq s1 2 6) s2)</code> should instead be
				3107	<code>(string-equal s1 s2 :start1 2 :end1 6)</code>
				3108	This is preferable because it does not cons.
				3109	</p>
				3110	<p>
				3111	You should use <code>ZEROP</code>,
				3112	<code>PLUSP</code>, or <code>MINUSP</code>,
				3113	instead of comparing a value to <code>0</code> or <code>0.0</code>.
				3114	</p>
				3115	<p>
				3116	You must not use exact comparison on floating point numbers,
				3117	since the vague nature of floating point arithmetic
				3118	can produce little "errors" in numeric value.
				3119	You should compare absolute values to a threshhold.
				3120	</p>
				3121	<p>
				3122	You must use <code>=</code> to compare numbers,
tunes@google.com	0c584cb	2012-10-11 17:06:57 +0000	[diff] [blame]	3123	unless you really mean for <code>0</code>,
				3124	<code>0.0</code> and <code>-0.0</code> to compare unequal,
				3125	in which case you should use <code>EQL</code>.
				3126	Then again, you must not usually use exact comparison
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	3127	on floating point numbers.
				3128	</p>
				3129	<p>
				3130	Monetary amounts should be using decimal (rational) numbers
				3131	to avoid the complexities and rounding errors
				3132	of floating-point arithmetic.
tunes@google.com	8c4c5ce	2012-10-12 23:16:43 +0000	[diff] [blame]	3133	Libraries such as
				3134	<a href="http://wukix.com/lisp-decimals">wu-decimal</a>
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	3135	may help you;
				3136	once again, if this library is not satisfactory, see above about
tunes@google.com	8c4c5ce	2012-10-12 23:16:43 +0000	[diff] [blame]	3137	<a href="#Using_Libraries">Using Libraries</a> and
				3138	<a href="#Open-Sourcing_Code">Open-Sourcing Code</a>.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	3139	</p>
				3140
				3141	</BODY>
				3142	</STYLEPOINT>
				3143	<STYLEPOINT title="Iteration">
				3144	<SUMMARY>
				3145	Use the appropriate form for iteration.
				3146	</SUMMARY>
				3147	<BODY>
				3148	<p>
Rommel M. Martinez	15afe03	2017-02-24 09:30:38 +0800	[diff] [blame]	3149	You should use simpler forms such as
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	3150	<code>DOLIST</code> or <code>DOTIMES</code>
				3151	instead of <code>LOOP</code>
				3152	in simple cases when you're not going to use any
				3153	of the <code>LOOP</code> facilities such as
				3154	bindings, collection or block return.
				3155	</p>
				3156	<p>
				3157	Use the <code>WITH</code> clause of <code>LOOP</code>
				3158	when it will avoid a level of nesting with <code>LET</code>.
				3159	You may use <code>LET</code> if it makes it clearer
				3160	to return one of bound variables after the <code>LOOP</code>,
				3161	rather than use a clumsy <code>FINALLY (RETURN ...)</code> form.
				3162	</p>
				3163	<p>
				3164	In the body of a <code>DOTIMES</code>,
				3165	do not set the iteration variable.
				3166	(CCL will issue a compiler warning if you do.)
				3167	</p>
				3168	<p>
				3169	Most systems use unadorned symbols in the current package
				3170	as <code>LOOP</code> keywords.
				3171	Other systems use actual <code>:keywords</code>
				3172	from the <code>KEYWORD</code> package
				3173	as <code>LOOP</code> keywords.
				3174	You must be consistent with the convention used in your system.
				3175	</p>
				3176	</BODY>
				3177	</STYLEPOINT>
				3178	<STYLEPOINT title="I/O">
				3179	<SUMMARY>
				3180	Use the appropriate I/O functions.
				3181	</SUMMARY>
				3182	<BODY>
				3183	<p>
				3184	When writing a server,
				3185	code must not send output to the standard streams such as
				3186	<code>STANDARD-OUTPUT</code> or <code>ERROR-OUTPUT</code>.
				3187	Instead, code must use the proper logging framework
				3188	to output messages for debugging.
				3189	We are running as a server, so there is no console!
				3190	</p>
				3191	<p>
				3192	Code must not use <code>PRINT-OBJECT</code>
mark@chromium.org	8190c13	2013-03-21 16:03:26 +0000	[diff] [blame]	3193	to communicate with a user —
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	3194	<code>PRINT-OBJECT</code> is for debugging purposes only.
				3195	Modifying any <code>PRINT-OBJECT</code> method
				3196	must not break any public interfaces.
				3197	</p>
				3198	<p>
				3199	You should not use a sequence of <code>WRITE-XXX</code>
				3200	where a single <code>FORMAT</code> string could be used.
				3201	Using format allows you
				3202	to parameterize the format control string in the future
				3203	if the need arises.
				3204	</p>
				3205	<p>
				3206	You should use <code>WRITE-CHAR</code> to emit a character
				3207	rather than <code>WRITE-STRING</code>
				3208	to emit a single-character string.
				3209	</p>
				3210	<p>
				3211	You should not use <code>(format nil "~A" value)</code>;
				3212	you should use <code>PRINC-TO-STRING</code> instead.
				3213	</p>
				3214	<p>
				3215	You should use <code>~<Newline></code>
				3216	or <code>~@<Newline></code> in format strings
				3217	to keep them from wrapping in 100-column editor windows,
				3218	or to indent sections or clauses to make them more readable.
				3219	</p>
				3220	<p>
				3221	You should not use <code>STRING-UPCASE</code>
				3222	or <code>STRING-DOWNCASE</code>
				3223	on format control parameters;
				3224	instead, it should use <code>"~:@(~A~)"</code> or <code>"~(~A~)"</code>.
				3225	</p>
				3226	<p>
				3227	Be careful when using the <code>FORMAT</code> conditional directive.
				3228	The parameters are easy to forget.
				3229	</p>
				3230	<dl>
				3231	<dt>No parameters, e.g. <code>"~[Siamese~;Manx~;Persian~] Cat"</code></dt>
				3232	<dd>
				3233	Take one format argument, which should be an integer.
				3234	Use it to choose a clause. Clause numbers are zero-based.
				3235	If the number is out of range, just print nothing.
				3236	You can provide a default value
				3237	by putting a <code>":"</code> in front of the last <code>";"</code>.
				3238	E.g. in <code>"~[Siamese~;Manx~;Persian~:;Alley~] Cat"</code>,
				3239	an out-of-range arg prints <code>"Alley"</code>.
				3240	</dd>
				3241	<dt><code>:</code> parameter, e.g. <code>"~:[Siamese~;Manx~]"</code></dt>
				3242	<dd>
				3243	Take one format argument. If it's <code>NIL</code>,
				3244	use the first clause, otherwise use the second clause.
				3245	</dd>
				3246	<dt><code>@</code> parameter, e.g. <code>"~@[Siamese ~a~]"</code></dt>
				3247	<dd>
				3248	If the next format argument is true,
				3249	use the choice, but do NOT take the argument.
				3250	If it's false, take one format argument and print nothing.
				3251	(Normally the clause uses the format argument.)
				3252	</dd>
				3253	<dt><code>#</code> parameter, e.g. <code>"~#[ none~; ~s~; ~s and ~s~]"</code></dt>
				3254	<dd>
				3255	Use the number of arguments to format
				3256	as the number to choose a clause.
				3257	The same as no parameters in all other ways.
				3258	Here's the full hairy example:
				3259	<code>"Items:~#[ none~; ~S~; ~S and ~S~:;~@{~#[~; and~] ~S~^ ,~}~]."</code>
				3260	</dd>
				3261	</dl>
				3262	</BODY>
				3263	</STYLEPOINT>
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	3264	</CATEGORY>
				3265
				3266	<CATEGORY title="Optimization">
				3267	<STYLEPOINT title="Avoid Allocation">
				3268	<SUMMARY>
				3269	You should avoid unnecessary allocation of memory.
				3270	</SUMMARY>
				3271	<BODY>
				3272	<p>
				3273	In a language with automatic storage management (such as Lisp or Java),
				3274	the colloquial phrase "memory leak" refers to situation
				3275	where storage that is not actually needed
				3276	nevertheless does not get deallocated,
				3277	because it is still reachable.
				3278	</p>
				3279	<p>
				3280	You should be careful that when you create objects,
				3281	you don't leave them reachable after they are no longer needed!
				3282	</p>
				3283	<p>
				3284	Here's a particular trap-for-the-unwary in Common Lisp.
				3285	If you make an array with a fill pointer, and put objects in it,
				3286	and then set the fill pointer back to zero,
				3287	those objects are still reachable as far as Lisp goes
				3288	(the Common Lisp spec says that it's still OK
				3289	to refer to the array entries past the end of the fill pointer).
				3290	</p>
				3291	<p>
				3292	Don't cons (i.e., allocate) unnecessarily.
				3293	Garbage collection is not magic.
				3294	Excessive allocation is usually a performance problem.
				3295	</p>
				3296	</BODY>
				3297	</STYLEPOINT>
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	3298	<STYLEPOINT title="Unsafe Operations">
				3299	<SUMMARY>
				3300	You must only use faster unsafe operations
				3301	when there is a clear performance need
				3302	and you can document why it's correct.
				3303	</SUMMARY>
				3304	<BODY>
				3305	<p>
				3306	Common Lisp implementations often provide backdoors
				3307	to compute some operations faster in an unsafe way.
				3308	For instance, some libraries provide arithmetic operations
				3309	that are designed to be used with fixnums only,
				3310	and yield the correct result faster if provided proper arguments.
				3311	The downside is that the result of such operations
				3312	is incorrect in case of overflow, and can
				3313	have undefined behavior when called with anything but fixnums.
				3314	</p>
				3315
				3316	<p>
				3317	More generally, unsafe operations
				3318	will yield the correct result faster
				3319	than would the equivalent safe operation
tunes@google.com	d6c053f	2013-09-19 17:26:22 +0000	[diff] [blame]	3320	if the arguments satisfy some invariant such as
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	3321	being of the correct type and small enough;
				3322	however if the arguments fail to satisfy the required invariants,
				3323	then the operation may have undefined behavior,
				3324	such as crashing the software, or,
				3325	which is sometimes worse, silently giving wrong answers.
				3326	Depending on whether the software is piloting an aircraft
				3327	or other life-critical device,
				3328	or whether it is accounting for large amounts money,
				3329	such undefined behavior can kill or bankrupt people.
				3330	Yet proper speed can sometimes make the difference between
tunes@google.com	d6c053f	2013-09-19 17:26:22 +0000	[diff] [blame]	3331	software that's unusably slow and software that does its job,
				3332	or between software that is a net loss
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	3333	and software that can yield a profit.
				3334	</p>
				3335	<p>
				3336	You must not define or use unsafe operations without both
				3337	profiling results indicating the need for this optimization,
				3338	and careful documentation explaining why it is safe to use them.
				3339	Unsafe operations should be restricted to internal functions;
				3340	you should carefully documented how unsafe it is
				3341	to use these functions with the wrong arguments.
				3342	You should only use unsafe operations
				3343	inside functions internal to a package and
				3344	you should document the use of the declarations,
				3345	since calling the functions with arguments of the wrong type
				3346	can lead to undefined behavior.
				3347	Use <code>check-type</code> in functions exported from a package
				3348	to sanitize input arguments,
				3349	so that internal functions are never passed illegal values.
				3350	</p>
				3351	<p>
				3352	On some compilers,
				3353	new unsafe operations
				3354	can usually be defined by combining
				3355	type declarations with an <code>OPTIMIZE</code> declaration
				3356	that has sufficiently high <code>SPEED</code> and low <code>SAFETY</code>.
				3357	In addition to providing more speed for production code,
				3358	such declarations may more helpful
				3359	than <code>check-type</code> assertions
				3360	for finding bugs at compile-time,
				3361	on compilers that have type inference.
				3362	These compilers may interpret those declarations as assertions
				3363	if you switch to safer and slower optimize settings;
				3364	this is good to locate a dynamic error in your code during development,
				3365	but is not to be used for production code since
				3366	it defeats the purpose of declarations as a performance trick.
				3367	</p>
tunes@google.com	d6c053f	2013-09-19 17:26:22 +0000	[diff] [blame]	3368
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	3369	</BODY>
				3370	</STYLEPOINT>
				3371	<STYLEPOINT title="DYNAMIC-EXTENT">
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	3372	<SUMMARY>
				3373	You should only use <code>DYNAMIC-EXTENT</code>
				3374	where it matters for performance,
				3375	and you can document why it is correct.
				3376	</SUMMARY>
				3377	<BODY>
				3378	<p>
mark@chromium.org	7b24563	2013-09-25 21:16:00 +0000	[diff] [blame]	3379	<code>DYNAMIC-EXTENT</code> declarations are
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	3380	a particular case of
				3381	<a href="#Unsafe_Operations">unsafe operations</a>.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	3382	</p>
				3383	<p>
mark@chromium.org	7b24563	2013-09-25 21:16:00 +0000	[diff] [blame]	3384	The purpose of a <code>DYNAMIC-EXTENT</code> declaration
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	3385	is to improve performance by reducing garbage collection
				3386	in cases where it appears to be obvious that an object's lifetime
				3387	is within the "dynamic extent" of a function.
				3388	That means the object is created at some point
				3389	after the function is called, and
				3390	the object is always inaccessible after the function exits by any means.
				3391	</p>
				3392	<p>
				3393	By declaring a variable or a local function <code>DYNAMIC-EXTENT</code>,
				3394	the programmer <em>asserts</em> to Lisp
				3395	that any object that is ever a value of that variable
				3396	or the closure that is the definition of the function
				3397	has a lifetime within the dynamic extent of the (innermost) function
				3398	that declares the variable.
				3399	</p>
				3400	<p>
				3401	The Lisp implementation is then free to use that information
				3402	to make the program faster.
				3403	Typically, Lisp implementations can take advantage of this knowledge
				3404	to stack-allocate:
				3405	</p>
				3406	<ul>
				3407	<li>
				3408	The lists created to store <code>&REST</code> parameters.
				3409	</li>
				3410	<li>
mark@chromium.org	7b24563	2013-09-25 21:16:00 +0000	[diff] [blame]	3411	Lists, vectors and structures allocated within a function.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	3412	</li>
				3413	<li>
				3414	Closures.
				3415	</li>
				3416	</ul>
				3417	<p>
				3418	If the assertion is wrong, i.e. if the programmer's claim is not true,
				3419	the results can be <em>catastrophic</em>:
				3420	Lisp can terminate any time after the function returns,
mark@chromium.org	7b24563	2013-09-25 21:16:00 +0000	[diff] [blame]	3421	or it can hang forever, or — worst of all —
				3422	it can produce incorrect results without any runtime error!
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	3423	</p>
				3424	<p>
				3425	Even if the assertion is correct,
				3426	future changes to the function might introduce
				3427	a violation of the assertion.
				3428	This increases the danger.
				3429	</p>
				3430	<p>
				3431	In most cases, such objects are ephemeral.
				3432	Modern Lisp implementations use generational garbage collectors,
				3433	which are quite efficient under these circumstances.
				3434	</p>
				3435	<p>
				3436	Therefore, <code>DYNAMIC-EXTENT</code> declarations
				3437	should be used sparingly. You must only use them if:
				3438	</p>
				3439	<ol>
				3440	<li>
				3441	There is some good reason to think that the overall effect
				3442	on performance is noticeable, and
				3443	</li>
				3444	<li>
				3445	It is absolutely clear that the assertion is true.
				3446	</li>
				3447	<li>
				3448	It is quite unlikely that the code will be changed
tunes@google.com	0c584cb	2012-10-11 17:06:57 +0000	[diff] [blame]	3449	in ways that cause the declaration to become false.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	3450	</li>
				3451	</ol>
				3452	<p>
				3453	Point (1) is a special case of
				3454	the principle of avoiding premature optimization.
				3455	An optimization like this only matters if such objects
				3456	are allocated at a very high rate, e.g. "inside an inner loop".
				3457	</p>
				3458	<p>
tunes@google.com	c55433c	2012-10-17 22:13:51 +0000	[diff] [blame]	3459	Note that is relatively easy to ascertain that
				3460	a function will not escape the dynamic extent of the current call frame
				3461	by analyzing where the function is called and
				3462	what other functions it is passed to;
				3463	therefore, you should somewhat wary of declaring a function
mark@chromium.org	7b24563	2013-09-25 21:16:00 +0000	[diff] [blame]	3464	<code>DYNAMIC-EXTENT</code>, but this is not a high-stress declaration.
tunes@google.com	c55433c	2012-10-17 22:13:51 +0000	[diff] [blame]	3465	On the other hand, it is much harder to ascertain that
				3466	none of the objects ever bound or assigned to that variable
mark@chromium.org	7b24563	2013-09-25 21:16:00 +0000	[diff] [blame]	3467	and none of their sub-objects
tunes@google.com	c55433c	2012-10-17 22:13:51 +0000	[diff] [blame]	3468	will escape the dynamic extent of the current call frame,
mark@chromium.org	7b24563	2013-09-25 21:16:00 +0000	[diff] [blame]	3469	and that they still won't in any future modification of a function.
tunes@google.com	c55433c	2012-10-17 22:13:51 +0000	[diff] [blame]	3470	Therefore, you should be extremely wary
				3471	of declaring a variable <code>DYNAMIC-EXTENT</code>.
				3472	</p>
				3473	<p>
mark@chromium.org	7b24563	2013-09-25 21:16:00 +0000	[diff] [blame]	3474	It's usually hard to predict the effect of such optimization on performance.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	3475	When writing a function or macro
mark@chromium.org	7b24563	2013-09-25 21:16:00 +0000	[diff] [blame]	3476	that is part of a library of reusable code,
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	3477	there's no a priori way to know how often the code will run.
				3478	Ideally, tools would be available to discover
				3479	the availability and suitability of using such an optimization
				3480	based on running simulations and test cases, but
				3481	in practice this isn't as easy as it ought to be.
				3482	It's a tradeoff.
				3483	If you're very, very sure that the assertion is true
mark@chromium.org	7b24563	2013-09-25 21:16:00 +0000	[diff] [blame]	3484	(that any object bound to the variable and any of its sub-objects
				3485	are only used within the dynamic extent of the specified scope),
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	3486	and it's not obvious how much time will be saved
				3487	and it's not easy to measure,
				3488	then it may be better to put in the declaration than to leave it out.
				3489	(Ideally it would be easier to make such measurements
				3490	than it actually is.)
				3491	</p>
				3492	</BODY>
				3493	</STYLEPOINT>
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	3494	<STYLEPOINT title="REDUCE vs APPLY">
				3495	<SUMMARY>
				3496	You should use <code>REDUCE</code>
				3497	instead of <code>APPLY</code> where appropriate.
				3498	</SUMMARY>
				3499	<BODY>
				3500	<p>
				3501	You should use <code>REDUCE</code>
				3502	instead of <code>APPLY</code> and a consed-up list,
				3503	where the semantics of the first operator argument
				3504	otherwise guarantees the same semantics.
				3505	Of course, you must use <code>APPLY</code>
				3506	if it does what you want and <code>REDUCE</code> doesn't.
mark@chromium.org	7b24563	2013-09-25 21:16:00 +0000	[diff] [blame]	3507	For instance:
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	3508	</p>
mark@chromium.org	7b24563	2013-09-25 21:16:00 +0000	[diff] [blame]	3509	<BAD_CODE_SNIPPET>
				3510	;; Bad
				3511	(apply #'+ (mapcar #'acc frobs))
				3512	</BAD_CODE_SNIPPET>
				3513	<CODE_SNIPPET>
				3514	;; Better
				3515	(reduce #'+ frobs :key #'acc :initial-value 0)
				3516	</CODE_SNIPPET>
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	3517	<p>
				3518	This is preferable because it does not do extra consing,
				3519	and does not risk going beyond <code>CALL-ARGUMENTS-LIMIT</code>
				3520	on implementations where that limit is small,
				3521	which could blow away the stack on long lists
tunes@google.com	1407ba7	2012-11-08 04:31:59 +0000	[diff] [blame]	3522	(we want to avoid gratuitous non-portability in our code).
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	3523	</p>
				3524	<p>
				3525	However, you must be careful not to use <code>REDUCE</code>
				3526	in ways that needlessly increase
				3527	the complexity class of the computation.
				3528	For instance, <code>(REDUCE 'STRCAT ...)</code> is <i>O(n^2)</i>
				3529	when an appropriate implementation is only <i>O(n)</i>.
				3530	Moreover, <code>(REDUCE 'APPEND ...)</code>
				3531	is also <i>O(n^2)</i> unless you specify <code>:FROM-END T</code>.
tunes@google.com	d6c053f	2013-09-19 17:26:22 +0000	[diff] [blame]	3532	In such cases, you MUST NOT use <code>REDUCE</code>,
mark@chromium.org	7b24563	2013-09-25 21:16:00 +0000	[diff] [blame]	3533	and you MUST NOT use <code>(APPLY 'STRCAT ...)</code>
				3534	or <code>(APPLY 'APPEND ...)</code> either.
				3535	Instead you MUST use proper abstractions
tunes@google.com	d6c053f	2013-09-19 17:26:22 +0000	[diff] [blame]	3536	from a suitable library (that you may have to contribute to)
				3537	that properly handles those cases
				3538	without burdening users with implementation details.
				3539	See for instance <code>UIOP:REDUCE/STRCAT</code>.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	3540	</p>
				3541
				3542	</BODY>
				3543	</STYLEPOINT>
				3544	<STYLEPOINT title="Avoid NCONC">
				3545	<SUMMARY>
				3546	You should not use <code>NCONC</code>;
				3547	you should use <code>APPEND</code> instead,
mark@chromium.org	7b24563	2013-09-25 21:16:00 +0000	[diff] [blame]	3548	or better, better data structures.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	3549	</SUMMARY>
				3550	<BODY>
				3551	<p>
				3552	You should almost never use <code>NCONC</code>.
				3553	You should use <code>APPEND</code>
				3554	when you don't depend on any side-effect.
				3555	You should use <code>ALEXANDRIA:APPENDF</code>
				3556	when you need to update a variable.
				3557	You should probably not depend on games
				3558	being played with the <code>CDR</code>
tunes@google.com	1407ba7	2012-11-08 04:31:59 +0000	[diff] [blame]	3559	of the current CONS cell
				3560	(which some might argue is suggested but not guaranteed by the specification);
				3561	if you do, you must include a prominent
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	3562	comment explaining the use of <code>NCONC</code>;
tunes@google.com	1407ba7	2012-11-08 04:31:59 +0000	[diff] [blame]	3563	and you should probably reconsider your data representation strategy.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	3564	</p>
				3565	<p>
				3566	By extension, you should avoid <code>MAPCAN</code>
				3567	or the <code>NCONC</code> feature of <code>LOOP</code>.
				3568	You should instead respectively use
				3569	<code>ALEXANDRIA:MAPPEND</code>
tunes@google.com	1407ba7	2012-11-08 04:31:59 +0000	[diff] [blame]	3570	and the <code>APPEND</code> feature of <code>LOOP</code>.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	3571	</p>
				3572	<p>
				3573	<code>NCONC</code> is very seldom a good idea,
				3574	since its time complexity class is no better than <code>APPEND</code>,
				3575	its space complexity class also is no better than <code>APPEND</code>
				3576	in the common case where no one else is sharing the side-effected list,
				3577	and its bug complexity class is way higher than <code>APPEND</code>.
				3578	</p>
				3579	<p>
				3580	If the small performance hit due
				3581	to <code>APPEND</code> vs. <code>NCONC</code>
				3582	is a limiting factor in your program,
				3583	you have a big problem and are probably using the wrong data structure:
				3584	you should be using sequences with constant-time append
				3585	(see Okasaki's book, and add them to lisp-interface-library),
				3586	or more simply you should be accumulating data in a tree
				3587	that will get flattened once in linear time
mark@chromium.org	7b24563	2013-09-25 21:16:00 +0000	[diff] [blame]	3588	after the accumulation phase is complete.
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	3589	</p>
				3590	<p>
				3591	You may only use <code>NCONC</code>, <code>MAPCAN</code>
				3592	or the <code>NCONC</code> feature of <code>LOOP</code>
				3593	in low-level functions where performance matters,
				3594	where the use of lists as a data structure has been vetted
				3595	because these lists are known to be short,
				3596	and when the function or expression the result of which are accumulated
tunes@google.com	1407ba7	2012-11-08 04:31:59 +0000	[diff] [blame]	3597	explicitly promises in its contract that it only returns fresh lists
				3598	(in particular, it can't be a constant quote or backquote expression).
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	3599	Even then, the use of such primitives must be rare,
				3600	and accompanied by justifying documentation.
				3601	</p>
				3602	</BODY>
				3603	</STYLEPOINT>
				3604	</CATEGORY>
				3605
tunes@google.com	8c4c5ce	2012-10-12 23:16:43 +0000	[diff] [blame]	3606	<CATEGORY title="Pitfalls">
tunes@google.com	13bb6e4	2012-10-15 20:57:01 +0000	[diff] [blame]	3607	<STYLEPOINT title="#'FUN vs. 'FUN">
				3608	<SUMMARY>
tunes@google.com	ed8e468	2012-11-29 00:14:33 +0000	[diff] [blame]	3609	You should usually refer to a function as <code>#'FUN</code> rather than <code>'FUN</code>.
tunes@google.com	13bb6e4	2012-10-15 20:57:01 +0000	[diff] [blame]	3610	</SUMMARY>
				3611	<BODY>
				3612	<p>
tunes@google.com	ed8e468	2012-11-29 00:14:33 +0000	[diff] [blame]	3613	The former, which reads as <code>(FUNCTION FUN)</code>,
				3614	refers to the function object, and is lexically scoped.
				3615	The latter, which reads as <code>(QUOTE FUN)</code>,
tunes@google.com	13bb6e4	2012-10-15 20:57:01 +0000	[diff] [blame]	3616	refers to the symbol, which when called
				3617	uses the global <code>FDEFINITION</code> of the symbol.
				3618	</p>
				3619	<p>
				3620	When using functions that take a functional argument
				3621	(e.g., <code>MAPCAR</code>, <code>APPLY</code>,
				3622	<code>:TEST</code> and <code>:KEY</code> arguments),
tunes@google.com	ed8e468	2012-11-29 00:14:33 +0000	[diff] [blame]	3623	you should use the <code>#'</code> to refer to the function,
tunes@google.com	13bb6e4	2012-10-15 20:57:01 +0000	[diff] [blame]	3624	not just single quote.
				3625	</p>
				3626	<p>
				3627	An exception is when you explicitly want dynamic linking,
				3628	because you anticipate that
				3629	the global function binding will be updated.
				3630	</p>
				3631	<p>
				3632	Another exception is when you explicitly want to access
				3633	a global function binding,
				3634	and avoid a possible shadowing lexical binding.
				3635	This shouldn't happen often, as it is usually a bad idea
				3636	to shadow a function when you will want to use the shadowed function;
				3637	just use a different name for the lexical function.
				3638	</p>
				3639	<p>
				3640	You must consistently use either <code>#'(lambda ...)</code>
				3641	or <code>(lambda ...)</code> without <code>#'</code> everywhere.
				3642	Unlike the case of <code>#'symbol</code> vs <code>'symbol</code>,
				3643	it is only a syntactic difference with no semantic impact,
				3644	except that the former works on Genera and the latter doesn't.
tunes@google.com	1407ba7	2012-11-08 04:31:59 +0000	[diff] [blame]	3645
tunes@google.com	13bb6e4	2012-10-15 20:57:01 +0000	[diff] [blame]	3646	You must use the former style if your code is intended as a library
				3647	with maximal compatibility to all Common Lisp implementations;
				3648	otherwise, it is optional which style you use.
				3649	<code>#'</code> may be seen as a hint
				3650	that you're introducing a function in expression context;
				3651	but the <code>lambda</code> itself is usually sufficient hint,
				3652	and concision is good.
				3653	Choose wisely, but above all,
				3654	consistently with yourself and other developers,
				3655	within a same file, package, system, project, etc.
				3656	</p>
				3657	<p>
				3658	Note that if you start writing a new system
				3659	in a heavily functional style,
				3660	you may consider using
				3661	<a href="http://cliki.net/lambda-reader">lambda-reader</a>,
mark@chromium.org	8190c13	2013-03-21 16:03:26 +0000	[diff] [blame]	3662	a system that lets you use the unicode character <code>λ</code>
tunes@google.com	13bb6e4	2012-10-15 20:57:01 +0000	[diff] [blame]	3663	instead of <code>LAMBDA</code>.
				3664	But you must not start using such a syntactic extension
				3665	in an existing system without getting permission from other developers.
				3666	</p>
				3667	</BODY>
				3668	</STYLEPOINT>
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	3669	<STYLEPOINT title="Pathnames">
				3670	<SUMMARY>
tunes@google.com	d6c053f	2013-09-19 17:26:22 +0000	[diff] [blame]	3671	Common Lisp pathnames are tricky. Be aware of pitfalls. Use <code>UIOP</code>.
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	3672	</SUMMARY>
				3673	<BODY>
				3674	<p>
				3675	It is surprisingly hard to properly deal with pathnames in Common Lisp.
				3676	</p>
				3677	<p>
tunes@google.com	d6c053f	2013-09-19 17:26:22 +0000	[diff] [blame]	3678	<code>ASDF 3</code> comes with a portability library <code>UIOP</code>
mark@chromium.org	7b24563	2013-09-25 21:16:00 +0000	[diff] [blame]	3679	that makes it <em>much</em> easier to deal with pathnames
				3680	portably — and correctly — in Common Lisp.
				3681	You should use it when appropriate.
tunes@google.com	d6c053f	2013-09-19 17:26:22 +0000	[diff] [blame]	3682	</p>
				3683	<p>
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	3684	First, be aware of the discrepancies between
				3685	the syntax of Common Lisp pathnames,
				3686	which depends on which implementation and operating system
				3687	you are using,
				3688	and the native syntax of pathnames on your operating system.
				3689	The Lisp syntax may involves quoting of special characters
				3690	such as <code>#\.</code> and <code>#\*</code>, etc.,
				3691	in addition to the quoting of
				3692	<code>#\\</code> and <code>#\"</code> within strings.
				3693	By contrast, your operating system's other
				3694	system programming languages
				3695	(shell, C, scripting languages)
				3696	may only have one layer of quoting, into strings.
				3697	</p>
				3698	<p>
				3699	Second, when using <code>MERGE-PATHNAMES</code>,
				3700	be wary of the treatment of the <code>HOST</code> component,
				3701	which matters a lot on non-Unix platforms
				3702	(and even on some Unix implementations).
				3703	You probably should be using
tunes@google.com	cf1841c	2014-03-18 00:14:41 +0000	[diff] [blame]	3704	<code>UIOP:MERGE-PATHNAMES*</code> or <code>UIOP:SUBPATHNAME</code>
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	3705	instead of <code>MERGE-PATHNAMES</code>,
				3706	especially if your expectations for relative pathnames
				3707	are informed by the way they work in Unix or Windows;
				3708	otherwise you might hit weird bugs whereby on some implementations,
				3709	merging a relative pathnames with an absolute pathname
				3710	results in overriding the absolute pathname's host
				3711	and replace it with the host from the value of
				3712	<code>DEFAULT-PATHNAME-DEFAULTS</code>
				3713	at the time the relative pathname was created.
				3714	</p>
				3715	<p>
				3716	Third, be aware that <code>DIRECTORY</code>
				3717	is not portable across implementations
				3718	in how it handles wildcards, sub-directories, symlinks, etc.
tunes@google.com	d6c053f	2013-09-19 17:26:22 +0000	[diff] [blame]	3719	There again, <code>UIOP</code> provides several
tunes@google.com	cf1841c	2014-03-18 00:14:41 +0000	[diff] [blame]	3720	common abstractions to deal with pathnames,
				3721	but only does so good a job.
				3722	For a complete portable solution, use IOLib —
				3723	though its Windows support lags behind.
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	3724	</p>
				3725	<p>
				3726	<code>LOGICAL-PATHNAME</code>s are not a portable abstraction,
				3727	and should not be used in portable code.
				3728	Many implementations have bugs in them, when they are supported at all.
				3729	SBCL implements them very well,
				3730	but strictly enforces the limitations on characters
tunes@google.com	d6c053f	2013-09-19 17:26:22 +0000	[diff] [blame]	3731	allowed by the standard, which restricts their applicability.
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	3732	Other implementations allow arbitrary characters in such pathnames,
				3733	but in doing so are not being conformant,
				3734	and are still incompatible with each other in many ways.
				3735	You should use other pathname abstractions,
				3736	such as <code>ASDF:SYSTEM-RELATIVE-PATHNAME</code> or
tunes@google.com	d6c053f	2013-09-19 17:26:22 +0000	[diff] [blame]	3737	the underlying <code>UIOP:SUBPATHNAME</code> and
mark@chromium.org	7b24563	2013-09-25 21:16:00 +0000	[diff] [blame]	3738	<code>UIOP:PARSE-UNIX-NAMESTRING</code>.
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	3739	</p>
				3740
				3741	<p>
				3742	Finally, be aware that paths may change between
				3743	the time you build the Lisp image for your application,
				3744	and the time you run the application from its image.
				3745	You should be careful to reset your image
				3746	to forget irrelevant build-time paths and
				3747	reinitialize any search path from current environment variables.
				3748	<code>ASDF</code> for instance requires you to reset its paths
tunes@google.com	cf1841c	2014-03-18 00:14:41 +0000	[diff] [blame]	3749	with <code>UIOP:CLEAR-CONFIGURATION</code>.
mark@chromium.org	7b24563	2013-09-25 21:16:00 +0000	[diff] [blame]	3750	<code>UIOP</code> provides hooks
				3751	to call functions before an image is dumped,
				3752	from which to reset or <code>makunbound</code> relevant variables.
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	3753	</p>
				3754
				3755	</BODY>
				3756	</STYLEPOINT>
tunes@google.com	8c4c5ce	2012-10-12 23:16:43 +0000	[diff] [blame]	3757	<STYLEPOINT title="SATISFIES">
				3758	<SUMMARY>
				3759	You must be careful when using a <code>SATISFIES</code> clause in a type specifier.
				3760	</SUMMARY>
				3761	<BODY>
				3762	<p>
				3763	Most Common Lisp implementations can't optimize
				3764	based on a <code>SATISFIES</code> type,
				3765	but many of them offer simple optimizations
				3766	based on a type of the form
				3767	<code>(AND FOO (SATISFIES BAR-P))</code>
				3768	where the first term of the <code>AND</code> clause
				3769	describes the structure of the object
				3770	without any <code>SATISFIES</code>
				3771	and the second term is the <code>SATISFIES</code>.
				3772	</p>
				3773	<BAD_CODE_SNIPPET>
				3774	(deftype prime-number () (satisfies prime-number-p)) ; Bad
				3775	</BAD_CODE_SNIPPET>
				3776	<CODE_SNIPPET>
				3777	(deftype prime-number () (and integer (satisfies prime-number-p)) ; Better
				3778	</CODE_SNIPPET>
				3779	<p>
				3780	However, <code>AND</code> in the <code>DEFTYPE</code> language
				3781	isn't a left-to-right short-circuit operator
				3782	as in the expression language;
				3783	it is a symmetrical connector that allows for reordering subterms
				3784	and doesn't guarantee short-circuiting.
				3785	Therefore, in the above example,
				3786	you cannot rely on the test for <code>INTEGER</code>ness
				3787	to protect the function <code>PRIME-NUMBER-P</code>
				3788	from being supplied non-integer arguments
				3789	to test for being of instances of the type.
				3790	Implementations may, and some <em>will</em>,
				3791	invoke <code>SATISFIES</code>-specified function
				3792	at compile-time to test various relevant objects.
				3793	</p>
				3794	<p>
				3795	That is why any function specified in a <code>SATISFIES</code> clause
				3796	MUST accept objects of any type as argument to the function,
mark@chromium.org	7b24563	2013-09-25 21:16:00 +0000	[diff] [blame]	3797	and MUST be defined within an <code>EVAL-WHEN</code>
				3798	(as well as any variable it uses or function it calls):
tunes@google.com	8c4c5ce	2012-10-12 23:16:43 +0000	[diff] [blame]	3799	</p>
				3800	<BAD_CODE_SNIPPET>
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	3801	(defun prime-number-p (n) ; Doubly bad!
tunes@google.com	8c4c5ce	2012-10-12 23:16:43 +0000	[diff] [blame]	3802	(let ((m (abs n)))
				3803	(if (<= m prime-number-cutoff)
				3804	(small-prime-number-p m)
				3805	(big-prime-number-p m))))
				3806	</BAD_CODE_SNIPPET>
				3807	<CODE_SNIPPET>
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	3808	(eval-when (:compile-toplevel :load-toplevel :execute) ; Better
tunes@google.com	8c4c5ce	2012-10-12 23:16:43 +0000	[diff] [blame]	3809	(defun prime-number-p (n)
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	3810	(when (integerp n) ; Better
tunes@google.com	8c4c5ce	2012-10-12 23:16:43 +0000	[diff] [blame]	3811	(let ((m (abs n)))
				3812	(if (<= m prime-number-cutoff)
				3813	(small-prime-number-p m)
				3814	(big-prime-number-p m))))))
				3815	</CODE_SNIPPET>
				3816	<p>
				3817	In particular, the above means that the
Ackermann Yuriy	7969290	2016-04-01 21:41:34 +1300	[diff] [blame]	3818	<a href="https://www.lispworks.com/documentation/HyperSpec/Body/t_satisf.htm">example</a>
tunes@google.com	8c4c5ce	2012-10-12 23:16:43 +0000	[diff] [blame]	3819	used in the Common Lisp Standard is erroneous:
				3820	<code>(and integer (satisfies evenp))</code>
				3821	is <em>not</em> a safe, conformant type specifier to use,
				3822	because <code>EVENP</code> will throw an error
				3823	rather than return <code>NIL</code>
				3824	when passed a non-integer as an argument.
				3825	</p>
				3826	<p>
				3827	Finally, there is a catch when your <code>DEFTYPE</code> code expands
				3828	to a <code>SATISFIES</code> with a dynamically generated function:
				3829	</p>
				3830	<ul>
				3831	<li>
				3832	You cannot control when implementations will or will not
				3833	expand a <code>DEFTYPE</code>.
				3834	</li>
				3835	<li>
				3836	The expansion itself cannot contain a function definition
				3837	or any code in the expression language.
				3838	</li>
				3839	<li>
				3840	You cannot control when the expansion is used,
				3841	it may happen in a different process
				3842	that didn't expand the definition.
				3843	</li>
				3844	</ul>
				3845	<p>
				3846	Therefore, you cannot merely create the function
				3847	as a side-effect of expansion
				3848	using <code>EVAL</code> at type-expansion time.
tunes@google.com	f981c5c	2012-10-14 13:47:38 +0000	[diff] [blame]	3849	The solution is to use
				3850	<code>ASDF-FINALIZERS:EVAL-AT-TOPLEVEL</code> instead.
				3851	See the very last point
				3852	in the discussion about <a href="#EVAL">EVAL</a>.
tunes@google.com	8c4c5ce	2012-10-12 23:16:43 +0000	[diff] [blame]	3853	</p>
				3854	<p>
				3855	Common Lisp is hard to satisfy.
				3856	</p>
				3857	</BODY>
				3858	</STYLEPOINT>
				3859	</CATEGORY>
				3860
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	3861	<HR/>
				3862
				3863	<small>Credits:
				3864	Adam Worrall, Dan Pierson, Matt Marjanovic, Matt Reklaitis,
				3865	Paul Weiss, Scott McKay, Sundar Narasimhan,
				3866	and several other people contributed.
				3867	Special thanks to Steve Hain,
				3868	and to the previous editors,
				3869	in reverse chronological order Dan Weinreb and Jeremy Brown.
				3870	</small>
				3871
				3872	<p align="right">
tunes@google.com	cf1841c	2014-03-18 00:14:41 +0000	[diff] [blame]	3873	Revision 1.28
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	3874	</p>
				3875
				3876
				3877	<address>
				3878	Robert Brown
				3879	</address>
				3880
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	3881	<address>
mark@chromium.org	8190c13	2013-03-21 16:03:26 +0000	[diff] [blame]	3882	<a HREF="mailto:tunes@google.com">François-René Rideau</a>
tunes@google.com	b1e9203	2012-10-10 18:50:04 +0000	[diff] [blame]	3883	</address>
				3884
				3885
				3886
				3887	</GUIDE>