/[slime]/slime/HACKING
ViewVC logotype

Contents of /slime/HACKING

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.10 - (show annotations)
Thu Jun 4 08:50:30 2009 UTC (4 years, 10 months ago) by heller
Branch: MAIN
CVS Tags: SLIME-2-3, SLIME-2-2, byte-stream, FAIRLY-STABLE, HEAD
Changes since 1.9: +11 -1 lines
Mention docstrings.
1 * The SLIME Hacker's Handbook -*- outline -*-
2
3 * Lisp code file structure
4
5 The Lisp code is organised into these files:
6
7 swank-backend.lisp:
8 Definition of the interface to non-portable features.
9 Stand-alone.
10
11 swank-<cmucl|...>.lisp:
12 Backend implementation for a specific Common Lisp system.
13 Uses swank-backend.lisp.
14
15 swank.lisp:
16 The top-level server program, built from the other components.
17 Uses swank-backend.lisp as an interface to the actual backends.
18
19 slime.el:
20 The Superior Lisp Inferior Mode for Emacs, i.e. the Emacs frontend
21 that the user actually interacts with and that connects to the
22 SWANK server to send expressions to, and retrieve information from
23 the running Common Lisp system.
24
25 contrib/*.lisp:
26 Lisp related code for add-ons to SLIME that are maintained by
27 their respective authors. Consult contrib/README for more
28 information.
29
30 * ChangeLog
31
32 For each change we make an entry in the ChangeLog file. This is
33 typically done using the command `add-change-log-entry-other-window'
34 (C-x 4 a). The message can be automatically extracted from the
35 ChangeLog to use in a CVS commit message by pressing C-c C-a in a
36 vc-mode or pcl-cvs commit buffer.
37
38 ChangeLog diffs are automatically sent to the slime-devel mailing list
39 each day as a sort of digest summary of the slime-cvs list.
40
41 There are good tips on writing ChangeLog entries in the GNU Coding Standards:
42 http://www.gnu.org/prep/standards/html_node/Style-of-Change-Logs.html#Style-of-Change-Logs
43
44 For information about Emacs's ChangeLog support see the `Change Log'
45 and `Change Logs and VC' nodes of the Emacs manual:
46 http://www.gnu.org/software/emacs/manual/html_node/emacs/Change-Log.html#Change-Log
47 http://www.gnu.org/software/emacs/manual/html_node/emacs/Change-Logs-and-VC.html#Change-Logs-and-VC
48
49
50 * Sending Patches
51
52 If you would like to send us improvements you can create a patch with
53 C-x v = in the buffer or manually with 'cvs diff -u'. It's helpful if
54 you also include a ChangeLog entry describing your change.
55
56 * Test Suite
57
58 The Elisp code includes a command `slime-run-tests' to run a test
59 suite. This can give a pretty good sanity-check for your changes.
60
61 Some backends do not pass the full test suite because of missing
62 features. In these cases the test suite is still useful to ensure that
63 changes don't introduce new errors. CMUCL historically passes the full
64 test suite so it makes a good sanity check for fundamental changes
65 (e.g. to the protocol).
66
67 Running the test suite, adding new cases, and increasing the number of
68 cases that backends support are all very good for karma.
69
70
71 * Source code layout
72
73 We use a special source file layout to take advantage of some fancy
74 Emacs features: outline-mode and "narrowing".
75
76 ** Outline structure
77
78 Our source files have a hierarchical structure using comments like
79 these:
80
81 ;;;; Heading
82 ;;;;; Subheading
83 ... etc
84
85 We do this as a nice way to structure the program. We try to keep each
86 (sub)section small enough to fit in your head: typically around 50-200
87 lines of code each. Each section usually begins with a brief
88 introduction, followed by its highest-level functions, followed by
89 their subroutines. This is a pleasing shape for a source file to have.
90
91 Of course the comments mean something to Emacs too. One handy usage is
92 to bring up a hyperlinked "table of contents" for the source file
93 using this command:
94
95 (defun show-outline-structure ()
96 "Show the outline-mode structure of the current buffer."
97 (interactive)
98 (occur (concat "^" outline-regexp)))
99
100 Another is to use `outline-minor-mode' to fold away certain parts of
101 the buffer. See the `Outline Mode' section of the Emacs manual for
102 details about that.
103
104 (This file is also formatted for outline mode. If you're reading in
105 Emacs you can play around e.g. by pressing `C-c C-d' right now.)
106
107 ** Pagebreak characters (^L)
108
109 We partition source files into chunks using pagebreak characters. Each
110 chunk is a substantial piece of code that can be considered in
111 isolation, that could perhaps be a separate source file if we were
112 fanatical about small source files (rather than big ones!)
113
114 The page breaks usually go in the same place as top-level outline-mode
115 headings, but they don't have to. They're flexible.
116
117 In the old days, when slime.el was less than 100 pages long, these
118 page breaks were helpful when printing it out to read. Now they're
119 useful for something else: narrowing.
120
121 You can use `C-x n p' (narrow-to-page) to "zoom in" on a
122 pagebreak-delimited section of the file as if it were a separate
123 buffer in itself. You can then use `C-x n w' (widen) to "zoom out" and
124 see the whole file again. This is tremendously helpful for focusing
125 your attention on one part of the program as if it were its own file.
126
127 (This file contains some page break characters. If you're reading in
128 Emacs you can press `C-x n p' to narrow to this page, and then later
129 `C-x n w' to make the whole buffer visible again.)
130
131
132 * Coding style
133
134 We like the fact that each function in SLIME will fit on a single
135 screen (80x20), and would like to preserve this property! Beyond that
136 we're not dogmatic :-)
137
138 In early discussions we all made happy noises about the advice in
139 Norvig and Pitman's _Tutorial on Good Lisp Programming Style_:
140 http://www.norvig.com/luv-slides.ps
141
142 For Emacs Lisp, we try to follow the _Tips and Conventions_ in
143 Appendix D of the GNU Emacs Lisp Reference Manual (see Info file
144 `elisp', node `Tips').
145
146 We use Emacs conventions for docstrings: the first line should be a
147 complete sentence to make the output of `apropos' look good. We also
148 use imperative verbs.
149
150 The biggest problem with SLIME's code base is feature creep. Keep in
151 mind that the Right Thing isn't always the Smart Thing. If you can't
152 find an elegant solution to a problem then you're probably solving the
153 wrong problem. It's often a good idea to simplify the problem and to
154 ignore rarely needed cases.
155
156 Remember that to rewrite a program better is the sincerest form of
157 code appreciation. When you can see a way to rewrite a part of SLIME
158 better, please do so!

  ViewVC Help
Powered by ViewVC 1.1.5