Posted by bboyes
on June 28, 2005 at 8:33 PM PDT
I say yes, we must -- if we want shared code to be easy to understand and use. And isn't that the whole point of a code-sharing community?
Well-written and documented code which has problems can be fixed by the community. Undocumented code is not only hard to use (maybe impossible), but cannot be maintained. So isn't conformance to some minimal coding standards essential for making this community a success.
How many of you have downloaded some code from the web, and been unable to use it because of 1) no meaningful comments in the code and 2) no other documentation such as useful examples? One of my senior project student teams struggled to use a poorly-documented AI engine downloaded from the web and finally gave up and wrote their own. Not exactly the kind of re-use of which Java code should be capable.
What standards? An easy metric is this: if your docs look like the Sun JDK javadocs you are probably OK. In fact Sun wrote some Java coding standards , so let's start there.
All of this was brought to the front of my consciousness by the JavaOne Monday session "Files From Mars" TS-1416 - analyzing Mars Rover data. The presentation focussed on three areas which are perhaps as interesting for what they don't mention as for what they do:
1) simplicity - to handle risk, cost, schedule
2) extensibility - to handle uncertainty
3) reuse - to handle risk, cost, schedule
Then, some corrolaries to the above:
a) Know your users:
b) one size does not fit all
c) Requirements docs are not enough
d) User assumptions are often wrong or incomplete
Nothing here about razzle-dazzle, performance, ease of use (per se), graphics capability, etc. But when you think about it, it's hard to argue with the first three topics. Simplicity should help with keeping on schedule, good performance, and ease of use, right? Extensibility means that others will be able to build on top of what has been done thus far, without changing the core code. Plus you too will be able to extend your code, when users demand a feature you didn't originally contemplate. Reuse means that you expect to get a lot of future benefit from present work, by applying (possibly modified) core code in other projects. Sounds like a pretty good mantra for open source projects.
The first enabler for extensibility and reuse is - documentation. In this session's project, fifty percent of the lines of code were comments. That sounds about right to me.
"It is doubtful whether a man ever brings his faculties to bear with their full force on a subject until he writes upon it."