TL:DR
Write ideas for humans around your code or it will die.
Explain, don't document.
Excellent blog post. However, you write
Passing It Over
At some point you may become disinterested in maintaining your
project. Maybe you've moved on to a new job or no longer use
your own project. Announce it on the mailing list, ask someone to
take over your project. Sooner or later, someone will help. ...
No, no, they won't. Why? Because, as you state earlier:
Claim that people who are not willing to read the code to figure
out even the most basic things are stupid and should flip burgers
instead.
There is a HUGE gulf between the user documentation and maintaining
the code. Just like there is a huge difference between using a car
and maintaining a car.
I have been trying to reverse-engineer the code the Clojure code base.
It uses red-black trees overlaid with a special immutable bit of
design. It uses a lot of optimizations, some of which assume a 32-bit
implementation. All without a comment anywhere. This is excellent code.
It is also unmaintainable.
(aside: the word "you" below is not aimed at the Michael, it is generic.
I am following Michael's usage and style from his blog post.)
.... /me drags out his street-worn soapbox. A crowd of two gathers.
Nobody, nobody, and I say again, NOBODY is going to pick up your
project. Why? Because they are going to look at your code pile and
cringe. There are thousands of good projects in Sourceforge.
Dead ones all. You too are writing dead code.
You have written layer upon layer upon layer of "improvements". You have
added partially worked out "features". You have removed the front-end
code but left the old code there because it is backward compatible with
version 0.0.0.1.2 which was never released.
Just to add to the confusion, you have ported your code to a dozen
platforms so you now have compiler switches, annotations, pragmas,
special Makefile stanzas, and library dependencies that will fail at the
next upgrade. You wrote autoconf macro scripts nobody understands.
You have install scripts for linux, an installer for Windows, and one
for the MAC. However, the linux script uses tools and directories that
only exist on your machine. The Windows installer is for Windows NT,
not Windows 8. The MAC installer doesn't check dependencies so it
installs but fails to run.
You need slime and leiningen but EVERYBODY has moved to smegle and
buildme. Leiningen is now 7 versions ahead of your version with
plugins that conflict with yours so your code no longer installs.
But not a word of explanation on any of it.
Your project is unmaintainable.
.... /me stacks another soapbox, with guitar for a ballad. The crowd thins.
Consider GNU Common Lisp, GCL.
It was originally called Austin Kyoto Common Lisp, AKCL.
It was written by Bill Schelter.
Bill was a FANTASTIC open source developer. He sat at my desk writing
AKCL. He found a bug in emacs, fetched a copy, fixed it, and uploaed
a patched version. In 1985. He was hardcore. He wrote amazing code
and never wrote comments, like all the greats.
AKCL eventually became GCL.
Bill is now dead. GCL was picked up by Camm Macquire. Camm is
another of those precious-few heavy hackers and GCL was the basis
of several huge projects. But Common Lisp has a real standard.
Does your project? Have a hundred people written a standard for you?
What is not explained is the crufty way that AKCL is built. It is
built on top of Kyoto Common Lisp. The Kyoto Common Lisp (KCL) license
says that you can't modify the code. It must be distributed unmodified.
So Bill wrote a "delta" program and everything he wrote was in delta
files off the original, unmodified KCL sources.
Thus, to maintain AKCL source code you have to use patch files.
Bill wrote valid patch files by hand. Diff -Naur valid files without diff.
Hardcore enough for you? Can you read directories full of patch files?
Oh, yeah, and since he was muttering to himself (aka programming)
he didn't even explain why the code needed to be written as patches.
The only reason I know is that I helped write pieces of AKCL and he
sat in my office.
Bill was an amazing programmer. But I now know he did it wrong.
.... /me stacks a bar of soap on top of the pile, steps up and ...
SCREAMS.
Maintaining and modifying source code is hard.
Porting it to multiple new platforms may require rewrites.
Maintaining library compatibility may require refactoring.
Upgrading installers may require code reorganizations.
Contributing it to debian may require restructuring.
It is all trivial and obvious to you. You wrote it. But finding and
fixing the fencepost bug in a red-black immutable tree implementation
borders on the impossible. You need to know that bit 31 overflows in a
strange way only on Alpha2 processors, causing a interrupt that is not
handled by the JVM. What does bit 31 mean? Why did the bug depend on it?
Your project exceeds 25,000 lines of code and every line counts. That's
approximately the number of lines in a 300 page textbook. Drag out any
mathematics reference book that has 300 pages of equations without
words. It's all there. Read the equations. Perfectly correct and
clear. However, it assumes you know a lot.
THAT's what you're saying to the next person to maintain your code.
It's all there. Read the code. Perfectly correct and clear.
.... /me looks down from the height with a weary eye ...
I got my own code back years after I wrote it.
I knew exactly what the code does.
I knew every byte that the compiler will lay down.
I knew how the data structure will be modified.
I wrote the code but I don't know WHY.
I knew it was needed because when I took it out the system broke.
I had to reverse-engineer the "why" of my own code.
It is VERY hard to reverse-engineer WHY someone wrote code.
There are no clues.
If you want your code to live, that is, if you want your code to
be used beyond your involvement you need to EXPLAIN THE CODE.
No, I don't mean Javadoc or Doxygen or any other code-decorating,
push-the-button, tree-killing, automated extraction thingie.
I mean that you need to write words that communicate IDEAS from
human to human. Real sentences with real words that you would say
to someone looking at the code. Functions should have a paragraph of
words. Code reviews should require an explanation with the code
before allowing it into the repository.
If you don't communicate the idea embodied in a piece of code in
words humans can understand, you are writing dead code for yourself.
If you want your code to LIVE, write WORDS for other HUMANS. Lots of
words. More words than code. Think of the difference between a math
reference textbook and a regular math book. Words.
I strongly recommend literate programming but feel free to ignore that.
Write words.
Tim Daly
Curmudgeon at Large
(see http://axiom-developer.org/axiom-website/litprog.html )
--
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clojure@googlegroups.com
Note that posts from new members are moderated - please be patient with your
first post.
To unsubscribe from this group, send email to
clojure+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
---
You received this message because you are subscribed to the Google Groups
"Clojure" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
