

Ask HN: How to write code that can be taken over by others? - patrickg

I am an experienced programmer and about to start a community funded project. If things work out fine, I will be payed for one month writing Lua code (for LuaTeX, but that won't matter I guess). After that month, the perfect situation would be a working piece of code where more people will jump in and fix bugs, enhance it and such.<p>This code will require expert knowledge (OpenType and TeX knowledge).<p>What are guidelines to write code so that other people have a chance to jump in? The current piece of code (which we want to replace) is mostly a black box to us and is too clever (for some definition of cleverness) and more or less undocumented (it has other problems as well, but they don't matter here).  What is your advice here? Some things are obvious: documentation, unit tests, getting other people involved as soon as possible, writing with "openness" in mind etc. But my fear is that I end with complex code which has the same problem as the now existing code and I will be the only person maintaining it.<p>Can you give advice how to lower the barrier for other people? Anybody has practical experience?
======
tjr
You say it's obvious, but really emphasize documentation:

A high-level description of what the software is supposed to do.

A medium-level description of roughly how the software is designed. Explain
how the user-level interface maps to the code modules, for example, what
functions are called when the user engages feature X? Feature Y? Feature Z?

In my opinion, that kind of documentation is immensely more useful than in-
the-code comments, but don't neglect that either. Use meaningful variable
names in all but the most trivial situations. Write real comment headers on
your functions, not just the bare minimum required by Doxygen-type systems.
It's hardly useful at all to document the parameters and types of your
function when you can see that looking at the function signature itself.
[Edit: ...so explain what the parameters are for.]

Will documentation have to be maintained? Yes. If you make major design
changes, you'll need to change the design document. If you make significant
code changes, you'll need to change the code comments.

But after being pulled in to fix/update/port a variety of hideously
undocumented projects, I cannot tell you how much good documentation along
these lines is appreciated.

Can a developer get by _without_ documentation, and just trace through the
code by hand? Of course. But please don't make us do that. :-)

~~~
patrickg
OK, so I guess I need to plan significant amount of time documenting. Not just
"the last day".

------
jameswyse
GitHub. I've also found annotated source code to be very helpful, it's quite
popular in the javascript world. Check out Locco:
<http://rgieseke.github.com/locco/>

~~~
patrickg
Awesome. Not much more to say. Thanks

------
PopaL
If you want to share your code with other people you could use github (it is
free for open source code).

~~~
patrickg
I use github extensively - very good suggestion! Thanks

------
tocomment
Write code for humans to read and only incidentally for a machine to execute.

~~~
patrickg
I try. I guess this is the hardest part.

