Planet

navi

home

PPS

about

screenshots

download

development

forum

Context Navigation

source: downloads/boost_1_34_1/more/lib_guide.htm @ 63

Last change on this file since 63 was 29, checked in by landauf, 16 years ago
updated boost from 1_33_1 to 1_34_1
File size: 32.0 KB

Line
1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2	<html>
3	<head>
4	<title>
5	Boost Library Requirements and Guidelines
6	</title>
7	<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
8	<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
9	<meta name="ProgId" content="FrontPage.Editor.Document">
10	<meta name="Microsoft Border" content="none, default">
11	</head>
12
13	<body bgcolor="#FFFFFF" text="#000000">
14	<table border="1" bgcolor="#007F7F" cellpadding="2">
15	<tr>
16	<td bgcolor="#FFFFFF">
17	<img src="../boost.png" alt="boost.png (6897 bytes)" width="277"
18	height="86">
19	</td>
20	<td>
21	<a href="../index.htm"><font face="Arial" color=
22	"#FFFFFF"><big>Home</big></font></a>
23
24	</td>
25	<td>
26	<a href="../libs/libraries.htm"><font face="Arial" color=
27	"#FFFFFF"><big>Libraries</big></font></a>
28	</td>
29	<td>
30	<a href="../people/people.htm"><font face="Arial" color=
31	"#FFFFFF"><big>People</big></font></a>
32	</td>
33	<td>
34
35	<a href="faq.htm"><font face="Arial" color=
36	"#FFFFFF"><big>FAQ</big></font></a>
37	</td>
38	<td>
39	<a href="index.htm"><font face="Arial" color=
40	"#FFFFFF"><big>More</big></font></a>
41	</td>
42	</tr>
43	</table>
44	<h1 align="left">
45
46	Boost Library Requirements and Guidelines
47	</h1>
48	<p align="left">
49	<a href="#Introduction">Introduction</a><br>
50	<a href="#Requirements">Requirements</a><br>
51	<a href="#License">License requirements</a><br>
52	<a href="#Portability">Portability requirements</a><br>
53
54	<a href="#Ownership">Ownership</a><br>
55	<a href="#Guidelines">Guidelines</a><br>
56	<a href="#Design_and_Programming">Design and
57	programming</a><br>
58	<a href="#Directory_structure">Directory structure and
59	filenames</a><br>
60	<a href="#Naming_consistency">Naming
61	consistency</a><br>
62
63	<a href="#Documentation">Documentation</a><br>
64	<a href="#Rationale">Rationale</a><br>
65	<a href=
66	"#Exception-specification">Exception-specification rationale</a><br>
67	<a href="#Naming">Naming conventions rationale</a><br>
68	<a href="#code_fonts">Source code fonts
69	rationale</a><br>
70
71	<a href="#Tabs">Tabs rationale</a><br>
72	<a href="#JavaScript">ECMAScript/JavaScript
73	rationale</a><br>
74	<a href="#Rationale_rationale">Rationale
75	rationale</a><br>
76	<a href="#Acknowledgements">Acknowledgements
77	rationale</a>
78	</p>
79
80	<h2 align="left">
81	<a name="Introduction" id="Introduction">Introduction</a>
82	</h2>
83	<p align="left">
84	This page describes requirements and guidelines for the content of a
85	library submitted to Boost.
86	</p>
87	<p align="left">
88	See the <a href="submission_process.htm">Boost Library Submission
89	Process</a> page for a description of the process involved.
90	</p>
91
92	<h2 align="left">
93	<a name="Requirements" id="Requirements">Requirements</a>
94	</h2>
95	<p>
96	To avoid the frustration and wasted time of a proposed library being
97	rejected, it must meets these requirements:
98	</p>
99	<ul>
100	<li>The license must meet the <a href="#License">license requirements</a>
101
102	below. Restricted licenses like the GPL and LGPL are not acceptable.
103	</li>
104	<li>The copyright <a href="#Ownership">ownership</a> must be clear.
105	</li>
106	<li>The library must be generally useful and not restricted to a narrow
107	problem domain.
108	</li>
109	<li>The library must meet the <a href="#Portability">portability
110	requirements</a> below.
111
112	</li>
113	<li>The library must come reasonably close to meeting the <a href=
114	"#Guidelines">Guidelines</a> below.
115	<ul>
116	<li>
117	<a href="#Design_and_Programming">Design and Programming</a>
118	</li>
119	<li>
120
121	<a href="#Directory_structure">Directory Structure</a>
122	</li>
123	<li>
124	<a href="#Documentation">Documentation</a>
125	</li>
126	</ul>
127	</li>
128	<li>The author must be willing to participate in discussions on the mailing
129	list, and to refine the library accordingly.
130	</li>
131
132	</ul>
133	<p>
134	There's no requirement that an author read the mailing list for a time
135	before making a submission. It has been noted, however, that submissions
136	which begin "I just started to read this mailing list ..." seem to fail,
137	often embarrassingly.
138	</p>
139	<h3 align="left">
140	<a name="License" id="License">License</a> requirements
141	</h3>
142	<p>
143	The preferred way to meet the license requirements is to use the <a href=
144	"../LICENSE_1_0.txt">Boost Software License</a>. See <a href=
145	"license_info.html">license information</a>. If for any reason you do not
146	intend to use the Boost Software License, please discuss the issues on the
147	Boost <a href="mailing_lists.htm#main">developers mailing list</a> first.
148	</p>
149
150	<p>
151	The license requirements:
152	</p>
153	<ul>
154	<li>Must be simple to read and understand.
155	</li>
156	<li>Must grant permission without fee to copy, use and modify the software
157	for any use (commercial and non-commercial).
158	</li>
159	<li>Must require that the license appear on all copies of the software
160	source code.
161	</li>
162	<li>Must not require that the license appear with executables or other
163	binary uses of the library.
164	</li>
165
166	<li>Must not require that the source code be available for execution or
167	other binary uses of the library.
168	</li>
169	<li>May restrict the use of the name and description of the library to the
170	standard version found on the Boost web site.
171	</li>
172	</ul>
173	<h3 align="left">
174	<a name="Portability" id="Portability">Portability</a> requirements
175	</h3>
176	<ul>
177
178	<li>
179	<p align="left">
180	A library's interface must portable and not restricted to a particular
181	compiler or operating system.
182	</p>
183	</li>
184	<li>
185	<p align="left">
186	A library's implementation must if possible be portable and not
187	restricted to a particular compiler or operating system.  If a
188	portable implementation is not possible, non-portable constructions are
189	acceptable if reasonably easy to port to other environments, and
190	implementations are provided for at least two popular operating systems
191	(such as UNIX and Windows).
192	</p>
193
194	</li>
195	<li>
196	<p align="left">
197	There is no requirement that a library run on C++ compilers which do
198	not conform to the ISO standard.
199	</p>
200	</li>
201	<li>
202	<p align="left">
203
204	There is no requirement that a library run on any particular C++
205	compiler.  Boost contributors often try to ensure their libraries
206	work with popular compilers.  The boost/config.hpp <a href=
207	"../libs/config/config.htm">configuration header</a> is the preferred
208	mechanism for working around compiler deficiencies.
209	</p>
210	</li>
211	</ul>
212	<p align="left">
213	Since there is no absolute way to prove portability, many boost submissions
214	demonstrate practical portability by compiling and executing correctly with
215	two different C++ compilers, often under different operating systems.
216
217	Otherwise reviewers may disbelieve that porting is in fact practical.
218	</p>
219	<h3 align="left">
220	<a name="Ownership" id="Ownership">Ownership</a>
221	</h3>
222	<p align="left">
223	Are you sure you own the library you are thinking of
224	submitting?   "How to Copyright Software" by MJ Salone, Nolo
225	Press, 1990 says:
226	</p>
227
228	<blockquote>
229	<p align="left">
230	Doing work on your own time that is very similar to programming you do
231	for your employer on company time can raise nasty legal problems.
232	In this situation, it's best to get a written release from your employer
233	in advance.
234	</p>
235	</blockquote>
236	<p align="left">
237	Place a copyright notice in all the important files you submit. Boost won't
238	accept libraries without clear copyright information.
239	</p>
240
241	<h2 align="left">
242	<a name="Guidelines" id="Guidelines">Guidelines</a>
243	</h2>
244	<p align="left">
245	Please use these guidelines as a checklist for preparing the content a
246	library submission.  Not every guideline applies to every library, but
247	a reasonable effort to comply is expected.
248	</p>
249	<h3>
250	<a name="Design_and_Programming" id="Design_and_Programming">Design and
251	Programming</a>
252
253	</h3>
254	<ul>
255	<li>Aim first for clarity and correctness; optimization should be only a
256	secondary concern in most Boost libraries.
257	</li>
258	</ul>
259	<ul>
260	<li>Aim for ISO Standard C++. Than means making effective use of the
261	standard features of the language, and avoiding non-standard compiler
262	extensions. It also means using the C++ Standard Library where applicable.
263	</li>
264	</ul>
265	<ul>
266
267	<li>Headers should be good neighbors. See the <a href="header.htm">header
268	policy</a>. See <a href="#Naming_consistency">Naming consistency</a>.
269	</li>
270	</ul>
271	<ul>
272	<li>Follow quality programming practices. See, for example, "Effective C++"
273	2nd Edition, and "More Effective C++", both by Scott Meyers, published by
274	Addison Wesley.
275	</li>
276	</ul>
277	<ul>
278
279	<li>Use the C++ Standard Library or other Boost libraries, but only when
280	the benefits outweigh the costs.  Do not use libraries other than the
281	C++ Standard Library or Boost. See <a href="library_reuse.htm">Library
282	reuse</a>.
283	</li>
284	</ul>
285	<ul>
286	<li>Read <a href="imp_vars.htm">Implementation Variation</a> to see how to
287	supply performance, platform, or other implementation variations.
288	</li>
289
290	</ul>
291	<ul>
292	<li>Read the <a href="separate_compilation.html">guidelines for libraries
293	with separate source</a> to see how to ensure that compiled link libraries
294	meet user expectations.
295	</li>
296	</ul>
297	<ul>
298	<li>Use the naming conventions of the C++ Standard Library (See <a href=
299	"#Naming">Naming conventions rationale</a>):<br>
300
301
302	<ul>
303	<li>Names (except as noted below) should be all lowercase, with words
304	separated by underscores.
305	</li>
306	<li>Acronyms should be treated as ordinary names (e.g.
307	<code>xml_parser</code> instead of <code>XML_parser</code>).
308	</li>
309	<li>Template parameter names begin with an uppercase letter.
310	</li>
311
312	<li>Macro (gasp!) names all uppercase and begin with BOOST_.
313	</li>
314	</ul>
315	</li>
316	</ul>
317	<ul>
318	<li>Choose meaningful names - explicit is better than implicit, and
319	readability counts. There is a strong preference for clear and descriptive
320	names, even if lengthy.
321	</li>
322	</ul>
323	<ul>
324
325	<li>Use exceptions to report errors where appropriate, and write code that
326	is safe in the face of exceptions.
327	</li>
328	</ul>
329	<ul>
330	<li>Avoid exception-specifications. See <a href="#Exception-specification">
331	exception-specification rationale</a>.
332	</li>
333	</ul>
334	<ul>
335
336	<li>Provide sample programs or confidence tests so potential users can see
337	how to use your library.
338	</li>
339	</ul>
340	<ul>
341	<li>Provide a regression test program or programs which follow the
342	<a href="test_policy.htm">Test Policies and Protocols</a>.
343	</li>
344	</ul>
345	<ul>
346	<li>Although some boost members use proportional fonts, tabs, and
347	unrestricted line lengths in their own code, boost's widely distributed
348	source code should follow more conservative guidelines:
349	<ul>
350
351	<li>Use fixed-width fonts.  See <a href="#code_fonts">fonts
352	rationale</a>.
353	</li>
354	<li>Use spaces rather than tabs. See <a href="#Tabs">tabs
355	rationale</a>.
356	</li>
357	<li>Limit line lengths to 80 characters.
358	</li>
359	</ul>
360
361	</li>
362	</ul>
363	<ul>
364	<li>End all documentation files (HTML or otherwise) with a copyright
365	message and a licensing message. See <a href="license_info.html">license
366	information</a> page for the preferred form.
367	</li>
368	</ul>
369	<ul>
370	<li>Begin all source files (including programs, headers, scripts, etc.)
371	with:<br>
372
373
374	<ul>
375	<li>A comment line describing the contents of the file.<br>
376
377	</li>
378	<li>Comments describing copyright and licensing: again, the preferred
379	form is indicated in the <a href="license_info.html">license
380	information</a> page<br>
381
382	<br>
383	Note that developers should not provide a copy of
384	<code>LICENSE_1_0.txt</code> with their libraries: Boost
385	distributions already include a copy in the Boost root directory.<br>
386
387	</li>
388	<li>A comment line referencing your library on the Boost web site. For
389	example:<br>
390	<br>
391
392	<code>//  See http://www.boost.org/libs/foo/ for library home
393	page.</code><br>
394	<br>
395	where <code>foo</code> is the directory name (see below) for the
396	library. As well as aiding users who come across a Boost file
397	detached from its documentation, some of Boost's automatic tools
398	depend on this comment to identify which library header files belong
399	to.
400	</li>
401	</ul>
402	</li>
403
404	</ul>
405	<ul>
406	<li>Make sure your code compiles in the presence of the <code>min()</code>
407	and <code>max()</code> macros. Some platform headers define
408	<code>min()</code> and <code>max()</code> macros which cause some common
409	C++ constructs to fail to compile. Some simple tricks can protect your code
410	from inappropriate macro substitution:<br>
411
412
413	<ul>
414	<li>If you want to call <code>std::min()</code> or
415	<code>std::max()</code>:<br>
416
417	<ul>
418	<li>If you do not require argument-dependent look-up, use
419	<code>(std::min)(a,b)</code>.
420	</li>
421
422	<li style="list-style: none">
423	<br>
424	</li>
425	<li>If you do require argument-dependent look-up, you should:
426	</li>
427	<li style="list-style: none">
428	<br>
429	<ul>
430	<li>
431
432	<code>#include <boost/config.hpp></code>
433	</li>
434	<li>Use <code>BOOST_USING_STD_MIN();</code> to bring
435	<code>std::min()</code> into the current scope.
436	</li>
437	<li>Use <code>min BOOST_PREVENT_MACRO_SUBSTITUTION
438	(a,b);</code> to make an argument-dependent call to
439	<code>min(a,b)</code>.
440	</li>
441
442	</ul>
443	</li>
444	</ul>
445	</li>
446	<li style="list-style: none">
447	<br>
448	</li>
449	<li>If you want to call
450	<code>std::numeric_limits<int>::max()</code>, use
451	<code>(std::numeric_limits<int>::max)()</code> instead.
452	</li>
453
454	<li style="list-style: none">
455	<br>
456	</li>
457	<li>If you want to call a <code>min()</code> or <code>max()</code>
458	member function, instead to doing <code>obj.min()</code>, use
459	<code>(obj.min)()</code>.<br>
460
461	</li>
462	<li style="list-style: none">
463	<br>
464	</li>
465	<li>If you want to declare or define a function or a member function
466	named <code>min</code> or <code>max</code>, then you must use the
467	<code>BOOST_PREVENT_MACRO_SUBSTITUTION</code> macro. Instead of writing
468	<code>int min() { return 0; }</code> you should write <code>int min
469	BOOST_PREVENT_MACRO_SUBSTITUTION () { return 0; }</code><br>
470
471	This is true regardless if the function is a free (namespace scope)
472	function, a member function or a static member function, and it
473	applies for the function declaration as well as for the function
474	definition.<br>
475	</li>
476	</ul>
477	</li>
478	</ul>
479	<h3>
480	<a name="Directory_structure" id="Directory_structure">Directory
481	Structure</a> and Filenames
482	</h3>
483
484	<ul>
485	<li>File and directory names must contain only <b>lowercase</b> ASCII
486	letters , numbers, underscores, and a period.  Leading character must
487	be alphabetic. Maximum length 31. Only a single period is permitted.
488	These requirements ensure file and directory names are relatively portable.
489	</li>
490	<li>Files intended to be processed by a C++ compiler as part of a
491	translation unit should have <b>a three-letter filename extension ending in
492	"pp"</b>. Other files should <i>not</i> use extensions ending in "pp". This
493	convention makes it easy to identify all of the C++ source in Boost.
494	</li>
495
496	<li>All libraries have at their highest level a primary directory named for
497	the particular library. See <a href="#Naming_consistency">Naming
498	consistency</a>. The primary directory may have sub-directories.
499	</li>
500	<li>For very simple libraries implemented entirely within the library
501	header, all files go in the primary directory (except headers, which go in
502	the boost header directory).
503	</li>
504	</ul>
505	<blockquote>
506	<p>
507	<b>Boost standard sub-directory names</b>
508
509	</p>
510	<table border="1" cellpadding="5">
511	<tr>
512	<td>
513	<b>Sub-directory</b>
514	</td>
515	<td>
516	<b>Contents</b>
517
518	</td>
519	<td>
520	<b>Required</b>
521	</td>
522	</tr>
523	<tr>
524	<td>
525	<code>build</code>
526
527	</td>
528	<td>
529	Library build files such as a Jamfile.
530	</td>
531	<td>
532	If any build files.
533	</td>
534	</tr>
535	<tr>
536	<td>
537
538	<code>doc</code>
539	</td>
540	<td>
541	Documentation (HTML) files.
542	</td>
543	<td>
544	If several doc files.
545	</td>
546	</tr>
547
548	<tr>
549	<td>
550	<code>example</code>
551	</td>
552	<td>
553	Sample program files.
554	</td>
555	<td>
556	If several sample files.
557	</td>
558
559	</tr>
560	<tr>
561	<td>
562	<code>src</code>
563	</td>
564	<td>
565	Source files which must be compiled to build the library.
566	</td>
567
568	<td>
569	If any source files.
570	</td>
571	</tr>
572	<tr>
573	<td>
574	<code>test</code>
575	</td>
576	<td>
577
578	Regression or other test programs or scripts.
579	</td>
580	<td>
581	If several test files.
582	</td>
583	</tr>
584	</table>
585	</blockquote>
586	<h4>
587	<a name="Redirection" id="Redirection">Redirection</a>
588
589	</h4>
590	<p>
591	The primary directory should always contain a file named index.html (or
592	index.htm). Authors have requested this so that they can publish URL's in
593	the form <i>http://www.boost.org/libs/lib-name</i> with the assurance a
594	documentation reorganization won't invalidate the URL. Boost's internal
595	tools are also simplified by knowing that a library's documentation is
596	always reachable via the simplified URL.
597	</p>
598	<p>
599	If the documentation is in a doc sub-directory, the primary directory
600	index.html file should just do an automatic redirection to the doc
601	subdirectory:
602	</p>
603	<blockquote>
604
605	<pre>
606	<html>
607	<head>
608	<meta http-equiv="refresh" content="0; URL=doc/index.html">
609	</head>
610	<body>
611	Automatic redirection failed, please go to
612	<a href="doc/index.html">doc/index.html</a>
613
614	</body>
615	</html>
616	</pre>
617	</blockquote>
618	<h3>
619	<a name="Naming_consistency">Naming consistency</a>
620	</h3>
621	<p>
622	As library developers and users have gained experience with Boost, the
623	following consistent naming approach has come to be viewed as very helpful,
624	particularly for larger libraries that need their own header subdirectories
625	and namespaces.
626	</p>
627
628	<p>
629	Here is how it works. The library is given a name that describes the
630	contents of the library. Cryptic abbreviations are strongly discouraged.
631	Following the practice of the C++ Standard Library, names are usually
632	singular rather than plural. For example, a library dealing with file
633	systems might chose the name "filesystem", but not "filesystems", "fs" or
634	"nicecode".
635	</p>
636	<ul>
637	<li>The library's primary directory (in parent <i>boost-root/libs</i>) is
638	given that same name.  For example,
639	<i>boost-root/libs/filesystem</i>.<br>
640
641
642	</li>
643	<li>The library's primary header directory (in parent
644	<i>boost-root/boost</i>) is given that same name. For example,
645	<i>boost-root/boost/filesystem</i>.<br>
646
647	</li>
648	<li>The library's primary namespace (in parent <i>::boost</i>) is given
649	that same name, except when there's a component with that name (e.g.,
650	<i>boost::tuple</i>), in which case the namespace name is pluralized. For
651	example, <i>::boost::filesystem</i>.
652	</li>
653
654	</ul>
655	<p>
656	When documenting Boost libraries, follow these conventions (see also the
657	following section of this document):
658	</p>
659	<ul>
660	<li>The library name is set in roman type.
661	</li>
662	<li>The library name is capitalized.
663	</li>
664	<li>A period between "Boost" and the library name (e.g., Boost.Bind) is
665	used if and only if the library name is not followed by the word "library".
666	</li>
667
668	<li>The word "library" is not part of the library name and is therefore
669	lowercased.
670	</li>
671	</ul>
672	<p>
673	Here are a few examples of how to apply these conventions:
674	</p>
675	<ul>
676	<li>Boost.Bind was written by Peter Dimov.
677	</li>
678	<li>The Boost Bind library was written by Peter Dimov.
679	</li>
680
681	<li>I regularly use Bind, a Boost library written by Peter Dimov.
682	</li>
683	</ul>
684	<h3>
685	<a name="Documentation" id="Documentation">Documentation</a>
686	</h3>
687	<p>
688	Even the simplest library needs some documentation; the amount should be
689	proportional to the need.  The documentation should assume the readers
690	have a basic knowledge of C++, but are not necessarily experts.
691	</p>
692
693	<p>
694	The format for documentation should be HTML, and should not require an
695	advanced browser or server-side extensions. Style sheets are acceptable.
696	ECMAScript/JavaScript is not acceptable. The documentation entry point
697	should always be a file named index.html or index.htm; see <a href=
698	"#Redirection">Redirection</a>.
699	</p>
700	<p>
701	There is no single right way to do documentation. HTML documentation is
702	often organized quite differently from traditional printed documents.
703	Task-oriented styles differ from reference oriented styles. In the end, it
704	comes down to the question: Is the documentation sufficient for the
705	mythical "average" C++ programmer to use the library successfully?
706	</p>
707	<p>
708	Appropriate topics for documentation often include:
709	</p>
710
711	<ul>
712	<li>General introduction to the library.
713	</li>
714	<li>Description of each class.
715	</li>
716	<li>Relationship between classes.
717	</li>
718	<li>For each function, as applicable, description, requirements
719	(preconditions), effects, post-conditions, returns, and throws.
720	</li>
721	<li>Discussion of error detection and recovery strategy.
722	</li>
723
724	<li>How to use including description of typical uses.
725	</li>
726	<li>How to compile and link.
727	</li>
728	<li>How to test.
729	</li>
730	<li>Version or revision history.
731	</li>
732	<li>Rationale for design decisions.  See <a href=
733	"#Rationale">Rationale rationale</a>.
734	</li>
735
736	<li>Acknowledgements.  See <a href="#Acknowledgements">Acknowledgments
737	rationale.</a>
738	</li>
739	</ul>
740	<p>
741	If you need more help with how to write documentation you can check out the
742	article on <a href="writingdoc/index.html">Writing Documentation for
743	Boost</a>.
744	</p>
745
746	<h2>
747	<a name="Rationale" id="Rationale">Rationale</a>
748	</h2>
749	<p>
750	Rationale for some of the requirements and guidelines follows.
751	</p>
752	<hr>
753	<h3>
754	<a name="Exception-specification" id=
755	"Exception-specification">Exception-specification</a> rationale
756	</h3>
757
758	<p>
759	Exception specifications [ISO 15.4] are sometimes coded to indicate what
760	exceptions may be thrown, or because the programmer hopes they will
761	improved performance.  But consider the following member from a smart
762	pointer:
763	</p>
764	<pre>
765	T& operator() const throw() { return ptr; }
766	</pre>
767	<p>
768	This function calls no other functions; it only manipulates fundamental
769	data types like pointers Therefore, no runtime behavior of the
770	exception-specification can ever be invoked.  The function is
771	completely exposed to the compiler; indeed it is declared inline Therefore,
772	a smart compiler can easily deduce that the functions are incapable of
773	throwing exceptions, and make the same optimizations it would have made
774	based on the empty exception-specification. A "dumb" compiler, however, may
775	make all kinds of pessimizations.
776	</p>
777
778	<p>
779	For example, some compilers turn off inlining if there is an
780	exception-specification.  Some compilers add try/catch blocks. Such
781	pessimizations can be a performance disaster which makes the code unusable
782	in practical applications.
783	</p>
784	<p>
785	Although initially appealing, an exception-specification tends to have
786	consequences that require <b>very</b> careful thought to understand. The
787	biggest problem with exception-specifications is that programmers use them
788	as though they have the effect the programmer would like, instead of the
789	effect they actually have.
790	</p>
791	<p>
792
793	A non-inline function is the one place a "throws nothing"
794	exception-specification may have some benefit with some compilers.
795	</p>
796	<hr>
797	<h3>
798	<a name="Naming" id="Naming">Naming</a> conventions rationale
799	</h3>
800	<p>
801	The C++ standard committee's Library Working Group discussed this issue in
802	detail, and over a long period of time. The discussion was repeated again
803	in early boost postings. A short summary:
804	</p>
805
806	<ul>
807	<li>Naming conventions are contentious, and although several are widely
808	used, no one style predominates.
809	</li>
810	<li>Given the intent to propose portions of boost for the next revision of
811	the C++ standard library, boost decided to follow the standard library's
812	conventions.
813	</li>
814	<li>Once a library settles on a particular convention, a vast majority of
815	stakeholders want that style to be consistently used.
816	</li>
817	</ul>
818	<hr>
819	<h3>
820
821	Source <a name="code_fonts" id="code_fonts">code fonts</a> rationale
822	</h3>
823	<p>
824	Dave Abrahams comments: An important purpose (I daresay the primary
825	purpose) of source code is communication: the documentation of intent. This
826	is a doubly important goal for boost, I think. Using a fixed-width font
827	allows us to communicate with more people, in more ways (diagrams are
828	possible) right there in the source. Code written for fixed-width fonts
829	using spaces will read reasonably well when viewed with a variable-width
830	font, and as far as I can tell every editor supporting variable-width fonts
831	also supports fixed width. I don't think the converse is true.
832	</p>
833	<hr>
834	<h3>
835	<a name="Tabs" id="Tabs">Tabs</a> rationale
836	</h3>
837
838	<p>
839	Tabs are banned because of the practical problems caused by tabs in
840	multi-developer projects like Boost, rather than any dislike in principle.
841	See <a href="mailing_lists.htm#archive">mailing list archives</a>. Problems
842	include maintenance of a single source file by programmers using tabs and
843	programmers using spaces, and the difficulty of enforcing a consistent tab
844	policy other than just "no tabs". Discussions concluded that Boost files
845	should either all use tabs, or all use spaces, and thus the decision to
846	stick with spaces.
847	</p>
848	<hr>
849	<h3>
850	ECMAScript/<a name="JavaScript" id="JavaScript">JavaScript</a> rationale
851	</h3>
852
853	<p>
854	Before the 1.29.0 release, two Boost libraries added ECMAScript/JavaScript
855	documentation. Controversy followed (see <a href=
856	"mailing_lists.htm#archive">mailing list archives</a>), and the developers
857	were asked to remove the ECMAScript/JavaScript. Reasons given for banning
858	included:
859	</p>
860	<ul>
861	<li>Incompatible with some older browsers and some text based browsers.
862	</li>
863	<li>Makes printing docs pages difficult.
864	</li>
865	<li>Often results in really bad user interface design.
866	</li>
867
868	<li>"It's just annoying in general."
869	</li>
870	<li>Would require Boost to test web pages for ECMAScript/JavaScript
871	compliance.
872	</li>
873	<li>Makes docs maintenance by other than the original developer more
874	difficult.
875	</li>
876	</ul>
877	<hr>
878	<h3>
879	<a name="Rationale_rationale" id="Rationale_rationale">Rationale
880	rationale</a>
881
882	</h3>
883	<p>
884	Rationale is defined as "The fundamental reasons for something; basis" by
885	the American Heritage Dictionary.
886	</p>
887	<p>
888	Beman Dawes comments:  Failure to supply contemporaneous rationale for
889	design decisions is a major defect in many software projects. Lack of
890	accurate rationale causes issues to be revisited endlessly, causes
891	maintenance bugs when a maintainer changes something without realizing it
892	was done a certain way for some purpose, and shortens the useful lifetime
893	of software.
894	</p>
895	<p>
896	Rationale is fairly easy to provide at the time decisions are made, but
897	very hard to accurately recover even a short time later.
898	</p>
899
900	<hr>
901	<h3>
902	<a name="Acknowledgements" id="Acknowledgements">Acknowledgements</a>
903	rationale
904	</h3>
905	<p>
906	As a library matures, it almost always accumulates improvements suggested
907	to the authors by other boost members.  It is a part of the culture of
908	boost.org to acknowledge such contributions, identifying the person making
909	the suggestion.  Major contributions are usually acknowledged in the
910	documentation, while minor fixes are often mentioned in comments within the
911	code itself.
912	</p>
913
914	<hr>
915	<p>
916	Revised
917	<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->
918	04 November, 2003<!--webbot bot="Timestamp" endspan i-checksum="39359" -->
919	</p>
920	<p>
921	© <a name="Copyright" id="Copyright">Copyright</a> Beman Dawes 2003.
922	</p>
923
924	<p>
925	Distributed under the Boost Software License, Version 1.0. (See
926	accompanying file <a href="../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy
927	at <a href=
928	"http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a>)
929	</p>
930	</body>
931	</html>

Note: See TracBrowser for help on using the repository browser.

Download in other formats: