Software is created off the strength of a “good idea”. From inside the development process, “code quality” is often thought of in terms of the number of bugs present in the code base. This is a useful metric, but it is not the only thing that determines the overall quality of the product. How intuitively a feature is implemented is also a factor in code quality.
How intuitive a feature is in software, has so far managed to avoid a quantifiable measure. That is, a “1 to 10 scale” that can accurately measure how intuitive software is, has yet to be developed. This can make it difficult to know if you have done the right thing when the software has been built. The phrase “to eat your own dog-food” is perhaps the best leveller for a new feature. Force the developers / UI experts / architects (anyone who influences the look-and-feel of the product) to use their own software and pretty soon, the rough edges get polished out.
I recently attended the
Borland Inprise CodeGear Embarcadero product launch for Delphi 2009. After many years in the marketing wilderness, it finally looks like they have found their niche market for Delphi and C++ builder. Their tools are viable options for “native Windows” applications. – That is, there is still significant demand for applications that require the “raw power” available using “unmanaged code”.
Additions to the Object Pascal syntax in this newest Delphi edition, see it become a really cool language. (Anonymous methods, closures and generics support). It was quite a frank and honest product demonstration from Nick Hodges. He was obviously keen to show-off the latest and greatest features of the product, but on the other hand open and responsive to suggestions and criticisms of the existing product.
One of the criticisms levelled against the current release (Delphi 2007) was about the product documentation (or lack thereof). Since the advent of Delphi 2005, the compiler has supported an nDoc style commenting system, to allow developers to “roll their own”. Nick made the passing comment that the developers were not particularly disciplined* to actually writing these comments. On the surface of it, it seems like an obvious solution to the lack of documentation.
Having since tried to use the feature myself, it becomes apparent why the developers are not bothering… It’s a great example of a “good feature – but in need of polish”. Here is my synopsis of what is wrong with it, the way it stands:
I’m not belittling the efforts of those responsible for nDoc, but its formatting syntax is inferior to Java’s self-documenting comment system. In my opinion, nDoc loses out by being fragments of XML, which make it less “human readable” than the Java equivalent.
One difference between Delphi / Object Pascal and Java or C# is the fact that the declarations for classes and functions are specified in an interface section, separately to their implementation (same source file, just a different section). The current nDoc parser used for Delpi’s HelpInsight feature (tool-tips that appear when hovering over functions) only finds comments that appear where the functions / classes are declared. For publically accessible functions, this is in the interface section. The most natural place to document the function is where it is implemented. I can see that this would be technically more difficult for the parser to manage, but that doesn’t give the programmers an excuse to be lazy.
The comments seem to need to be in units that are explicitly included in the project. Despite the fact that the compiler can resolve/match symbols that appear in source files anywhere on the source path, the nDoc comment resolution can’t. You need to add your unit with the comments to the Project (.dpr / .dproj) file.
The nDoc parser appears to be buggy. Most notably, the first function (Object Pascal still allows you to have functions that don’t live in a class) will not be found. The way around this is to declare either a dummy function, or a dummy type. Neither of these need to have their own nDoc commenting but it may help you to remember why you wrote in another declaration of the integer type…
Nick Hodges invited the audience to contact him if we had ideas on how to improve Delphi. Now I’ve had a chance to flesh out what I see as being wrong with HelpInsight, I might just do that!
* I’m paraphrasing here. He definitely did not use this terminology…