Ask HN: How to write code that can be taken over by others? | Hacker News Reader

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

4 pointspatrickg8 comments

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.

This code will require expert knowledge (OpenType and TeX knowledge).

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.

Can you give advice how to lower the barrier for other people? Anybody has practical experience?

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. :-)

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

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/

Awesome. Not much more to say. Thanks

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

I use github extensively - very good suggestion! Thanks

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

I try. I guess this is the hardest part.

Reply on news.ycombinator.com