Programmers are not known to be social creatures. It’s an unfortunate reputation really, considering that programmers spend most of their lives writing their thoughts to each other - they should be right up there in the social landscape with Paris Hilton and Lady Gaga. The problem of course is that programmers never recognise the social aspect of their work. They think they write code for computers. Nothing could be further from the truth.
In fact, it’s difficult to get a computer to misunderstand your code - though not impossible. If you compile with the highest (non trivial) warnings enabled it will spew out a lot of complaints, sometime nitpicking - to the effect of "You know... you shouldn't be putting a larger variable into a smaller one because you might lose some of the contents... not judging you or anything, just saying." A human in contrast will misunderstand the intention of your code quite easily, because they will create a story in their heads that seems to match the text they are viewing and that story may not reflect the reality the compiler sees.
That’s because humans are very good at filling in the missing details with ones contrived in their own heads from experience based on reality. The shadowy figure approaching the shower curtain with a knife is probably not there to cut a piece of cake. A compiler wouldn’t blink twice if the psycho pulled the curtain aside and decided to sing happy birthday and offer a piece of cake to Marion instead. It would consider such an occurrence natural and logical. It would however scream bloody murder if the knife was of a wrong size.
Compilers therefore validate the syntax of your code. Other programmers validate the semantics (the logic). Take care when writing code not just to please the compiler but to also please other programmers who read your code. The latter is easy, you could always crank up the warning level to the highest possible and ensure that you compile cleanly while the former is more difficult as there is no real way to know what other people will imagine when reading your code. The problem with writing social code there is no single validator of what is acceptable and each persons standards might differ.
That said, programmer friendly code has something in common with etiquette. It’s about understanding what’s expected of you by others around you in a given set of circumstances. It’s something gained over time with experience. A new programmer writing code into a clean code base may feel like a vulture at a posh dinner party at the beginning but he soon learns to write code that “feels” good to other programmers by looking at the code already present. On the contrary a programmer that starts writing with a badly written and ill kept code base might develop a similar habit of coding.
Coding is therefore an inherently social activity but few take it to account when designing software. Programmers like to think in terms of space and time complexity, or the overall pattern of the design or if the technologies used conform to the latest trends on the developer catwalk or the testability of the code or… I could go on and on but they miss one fundamental question, “Who will read my code?”
In a sense programming is like any other form of writing, you must know your audience. A teacher may not need to write about the ills of using too much fertiliser to a primary class learning about what a farmer does, but a professor of agriculture should. The same goes for API’s, when writing code think about the audience that will read it. If you expect the programmers to be mature then you can expose more options to them through the API. Exposing more options will increase the complexity of learning to use the code, however it will also increase it’s flexibility. On the other hand, if you expect your code to be used as a library by novice application programmers who write business logic then you should try to make the code as restrictive as possible to avoid the kind of things things that are known to happen to orangutans wielding chainsaws 1.
A good program makes easy reading. It’s like a well written book that doesn’t spend an entire chapter describing the topology of the unfortunate spinster’s sister’s blister. It knows that details are important but doesn’t shower the reader with the them from the outset. It understands encapsulation of complexity and hides logic of enormous complexity inside understandable function names like TheRiseAndFallOfEmpires(). For people unlike compilers grow tired and weary, even seasoned programmers will stumble and fall and so the great enemy of the programmer is mental fatigue rather than compiler errors which will see the code the same through every run. A programmer will see the code differently if he had a good night of sleep before. A well written program keeps this in mind and creates reading that is neither too complex or abstract, reading that will communicate the logic of the program without requiring too much work on part of the reader.
A good program is written to be discoverable that mortals may know it’s end from it’s beginnings. It uses understandable file names rather than incomprehensible ones that do nothing in communicating their position or purpose in the grand scheme of things. It recognises that the writer of the program has a leaky bucket with which to draw from the well of his intentions. No matter how hard he tries the writer of the program may keep some part of the intended behaviour in his own mind and readers must discern that which is not there in the code from that which is. It provides enough points of reference not just to understand the logic that is seen but the intentions that are not. A good program is written by a good programmer.
A good programmer may above all else be one that thinks of his fellows. Those who would read his letters after he is long gone.
[1] I am not by any way comparing novice application logic programmers to chainsaws.