not just random

I just started reading The Best Software Writing I: Selected and Introduced by Joel Spolsky. The first article led me to Ken Arnold’s Style is Substance:

I’ll state it right out: For almost any mature language (C, Java, C++, Python, Lisp, Ada, FORTRAN, Python, Smalltalk, sh, javascript, …) coding style is an essentially solved problem, and we ought to stop worrying about it. And to stop worrying about it will require worrying about it a lot first, because the only way to get from where we are to a place where we stop worrying about style is to enforce it as part of the language.

Yup. I’m really saying that. I’m saying that, for example, the next ANSI C update should define the standard K&R C programming style into the language grammar. Programs that use any new features should be required to be in K&R style or be rejected by the compiler as syntactically illegal.

I really like that.

Of course I am all for creativity. Having spent way too much time in the past weeks (months) working through source codes that appear to follow all kinds of different style variations, I am getting tired of it though. Very tired. This is the wrong kind of creativity.

Being able to enforce a style guide directly via the compiler would be extremely helpful in this case. No more dragging everyone in a poorly ventilated conference room and trying to convince people that following a consistent style convention is A Good Thing.

No more arguing the merits of one style over the other. I mean - please!

In short: That article made my day. I am already looking forward to other gems in the book and I think I am going to look more seriously into Python. Maybe there might even be a point in at least considering a pre-compiler of sorts, some routine that checks the input source code for correct style, before sending it on to the actual compiler. Hm …

Ever been in that situation? A product has been in development, from the ground up for three to four years. There have been several sales and the product is overall regarded as rather successful. In fact, it grows much bigger than initially expected. An infrastructure forms around it, staffing demands grow, etc. etc. until at some point the company is big enough that an actual HR department is justified. Then, the core developer decides to move on and is off to greener pastures. Ouch.

It gets worse: He or she did in fact never bother to create any elaborate documentation of the architecture or any important design decisions. It’s all in his head.

Well.

I overheard a similar description the other day. Interestingly, the speaker concluded his story with the following statement: “We did not need to create documentation for anything back then.” Nodding, chuckling … then the conversation moved on to other subjects.

I could not forget about this though. On the one hand, I do empathize with the spirit: You’re having a high tech startup, so you work hard, really hard to get out that product. You have only one or two people hacking away on the code. You’re exploring new territory and have to hurry, because the competition could enter your market any moment. You really a) have no time for documenting, b) see no reason, because the application is far from complex at that point, and finally c) only need a minimum of documentation simply because there is not a large team involved and thus pretty few things to be communicated. No time for breaks, because you and your team are busy inventing the future and selling the half-ready program to cash-wielding prospects who would prefer to have the final result tomorrow. It’s a pretty exciting environment.

Not creating effective documentation in that early stage of a product is a horrible mistake.

Here are just some reasons for this:

• As more and more requirements are revealed software tends to gain and not lose complexity.
• The software (or rather, the code base) will end up being in use far longer than the original developers could possibly anticipate.
• Teams will grow, requiring a great information overhead. It can be very painful process, trying to discover the existing knowledge about architecture, design or features.
• People will move on. They may move within the company or sign on somewhere else. Either way, the transition can be quite slow and inefficient. If the former main developer is suddenly busy running the company he won’t have much time explaining database table structures.
• The early knowledge may well be core knowledge, if the early development focused on the most important features of the application.

There is of course no easy answer, because some of those earlier objections may well appear quite valid. For some time anyway. Then, you better have a plan on how to transition smoothly to a good documentation process. Otherwise you might just find yourself in an unlucky scenario five years down the road.