From: Mark Wooding Date: Sat, 27 Jul 2019 13:15:41 +0000 (+0100) Subject: STYLE: Make this document cover multiple languages. X-Git-Url: https://git.distorted.org.uk/~mdw/sod/commitdiff_plain/cbed66ad2c8fd59081c900be8f94956ebe181a23 STYLE: Make this document cover multiple languages. Add a language-neutral section to the top, and demote all of the Lisp stuff by a level. --- diff --git a/STYLE b/STYLE index a6a4f5c..49ad150 100644 --- a/STYLE +++ b/STYLE @@ -1,6 +1,35 @@ -Notes on Lisp style +Notes on coding style -* Language subset and extensions +* General + +** Layout + +Lines are 77 characters at most, except for strange special effects. +Don't ask. This is not negotiable, though. Don't try to tell me that +your monitor is very wide so you can read longer lines. My monitor is +likely at least as wide. On the other hand, most lines are easily short +enough to fit in my narrow columns, so the right hand side of a wide +window would be mostly blank. This seems wasteful to me, when I could +fill that space with more code. + +Horizontal whitespace for layout purposes -- i.e., indentation and +alignment, rather than just separating words -- consists of as many tabs +as possible, followed by as many spaces as necessary to reach the target +column. Tab stops occur at every eight columns. You can tell this +because when you cat a file to your terminal, that's how the tabs +appear. Editors which disagree about this are simply wrong. + +My indentation quantum is usually two columns. It seems that some +modern editors are deeply confused, and think that tab width and +indentation quantum are the same thing, but they aren't. Such broken +editors will make a hopeless mess of my code. If you have the +misfortune to use such an editor, maybe you could contribute patches to +fix it. + + +* Lisp style + +** Language subset and extensions None of ANSI Common Lisp is off-limits. @@ -53,8 +82,7 @@ suite, which makes additional use of ~xlunit~. Running the test suite isn't essential to getting the translator built, so this isn't as much of a problem. - -* Layout +** Layout I pretty much let Emacs indent my code for me, based on information collected by SLIME. Some exceptions: @@ -90,28 +118,6 @@ collected by SLIME. Some exceptions: mandatory positional arguments that I had to split them. So far, this situation hasn't come up. -Lines are 77 characters at most, except for strange special effects. -Don't ask. This is not negotiable, though. Don't try to tell me that -your monitor is very wide so you can read longer lines. My monitor is -likely at least as wide. On the other hand, most lines are easily short -enough to fit in my narrow columns, so the right hand side of a wide -window would be mostly blank. This seems wasteful to me, when I could -fill that space with more code. - -Horizontal whitespace for layout purposes -- i.e., indentation and -alignment, rather than just separating words -- consists of as many tabs -as possible, followed by as many spaces as necessary to reach the target -column. Tab stops occur at every eight columns. You can tell this -because when you cat a file to your terminal, that's how the tabs -appear. Editors which disagree about this are simply wrong. - -My indentation quantum is usually two columns. It seems that some -modern editors are deeply confused, and think that tab width and -indentation quantum are the same thing, but they aren't. Such broken -editors will make a hopeless mess of my code. If you have the -misfortune to use such an editor, maybe you could contribute patches to -fix it. - Lisp code does have a tendency to march across to the right quite rapidly given a chance. I have a number of strategies for dealing with this. @@ -126,8 +132,7 @@ this. + Shrug my shoulders and let code dribble down the right hand side for a bit. - -* Packages and exporting +** Packages and exporting A package collects symbols which are given meanings in one or more source files. If a package's code is all in one file, then the package @@ -159,8 +164,7 @@ See ~doc/list-symbols.lisp~ for more sophisticated reporting. (In particular, this identifies what kind of thing(s) each external symbol names.) - -* Comments and file structuring +** Comments and file structuring A file starts with a big ~;;;~ comment bearing the Emacs ~-*-lisp-*-~ marker, a quick description, and copyright and licensing boilerplate. I @@ -212,8 +216,7 @@ Files end, as a result of long tradition, with a comment : ;;;----- That's all, folks -------------------------------------------------- - -* Macro style +** Macro style I don't mind complicated macros if they're doing something worthwhile. They need to have good documentation strings, though. @@ -226,8 +229,7 @@ It's extremely bad taste for a macro to evaluate its evaluable parameters in any order other than strictly left to right, or to evaluate them more than once. - -* Data structures +** Data structures I've tended to be happy with plain lists for homogeneous-ish collections. Strongly heterogeneous collections (other than input @@ -283,8 +285,7 @@ making a new structure type. I tend to tidy up a few rough edges. to roll up your sleeves and mess with ~&aux~ parameters to pull it off. - -* Naming +** Naming I'm a traditionalist in some ways, and one of the reasons I like Lisp is the richness of its history and tradition. @@ -306,8 +307,7 @@ with the same intention, and the bindings are then explicitly ignored with a declaration. The names begin ~hunoz~, ~hukairz~, and (I think) ~huaskt~. - -* Declarations +** Declarations The code is light on declarations, other than ~ignore~ and similar used to muffle warnings. The macros try to do sensible things with