Wandering Thoughts archives

2010-10-27

An extra problem with not documenting things in open source modules

Programmers are famous for not doing a great job of documenting the interfaces of their projects (whether these are libraries with APIs, protocols, programming languages, or whatever). The problems that this causes for people who are trying to use your work are well known, but it's recently struck me that open source projects in particular have an additional issue.

In the absence of documentation, people working with open source projects can always read the source to find out how to do something, to discover the interface that the project written down yet. But when you do so, you're left with a question: is what you've found something that you should actually be using?

There's at least three possibilities. First, you could have found the right answer, the correct interface to use for what you want to do, and it just hasn't been documented yet. Second, you could have found an unsupported and unstable internal interface or an implementation detail. Third, you could have found an experimental interface that the project authors haven't finalized yet (and thus haven't documented).

(I'm going to assume here that the name of the interface and other details in the code give an outsider no obvious clues. Remember that the people searching through the guts of your library probably don't have deep experience with the code base and your conventions.)

The quality of documentation matters here. The more clearly patchy and incomplete the documentation, the less guidance it can give you about which possibility you've hit; conversely, the more complete the documentation the more you can infer something from things not being documented. How the documentation is created also matters; people can infer one thing from entirely hand-written documentation and another from documentation that is at least partly automatically extracted from source code.

Of course, an explicit mention of this issue in your documentation helps to some degree, but make sure that it's believable and useful. Saying 'anything not mentioned here is internal and unsupported' is pretty pointless if your documentation is clearly incomplete, because you give people the choice of either ignoring your warning or ignoring your project entirely. (You lose either way.)

(I don't think that this issue is completely avoided in systems where you have to explicitly mark things to be publicly visible, just reduced somewhat. Of course you could always modify your build system so that basic interface documentation is automatically extracted and only things with such documentation are marked as publicly visible.)

programming/OpenSourceNoDocIssue written at 23:58:15; Add Comment

A modern VCS mistake enabled by working on live trees

I've written before about sysadmin style use of version control, where we typically use a VCS for documenting the live tree instead of developing something. Recently I ran into a mistake that modern VCSes and this style of working combine together to enable: deleting a file from the live directory tree but forgetting to delete it from the VCS.

Since the live tree is, well, live, deleting the file actually takes effect and so you don't notice anything wrong. In fact, in a sense nothing is wrong except that your VCS repository no longer accurately reflects the state of the live system.

(If you make a habit of running 'hg status' or the equivalent you may notice the complaints about this, but our working practice is 'hg diff, make changes, hg diff, hg commit', and at least in our current version of Mercurial this produces no complaints; as a result, we sailed along in this situation for some time.)

There's at least two dangers of this situation. The first is that you haven't captured information about when the file was actually deleted from your live system, and you may want it someday (you can sometimes guess based on other changes). The second is that if you ever have to actually check out the tree (in any version, either the current one or an older one), these deleted files will spring back to life. Sometimes this is just surprising and distracting clutter, but it could be a problem if the file is in some place where its mere presence will cause it to be used for something.

(If the removed file has to be mentioned in a configuration file in order to do anything, having it reappear is generally harmless because you will have also committed the change to the configuration file that stops using it.)

There's also the mirror image mistake of adding a file to the live tree without committing it to the VCS repository, but we haven't made that one yet.

sysadmin/VCSRemovingFilesMistake written at 01:56:47; Add Comment


Page tools: See As Normal.
Search:
Login: Password:
Atom Syndication: Recent Pages, Recent Comments.

This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.