Following on from my post regarding JclExprEval of the Jedi Code Library, Barry Kelly, left me a comment that in fact the unit had been documented, and he gave me a link to it.
I don't think I'm going to even bother downloading it. I can't really see what the documentation can give me that looking at the code hasn't (although being a curious fellow, I no doubt will). The is self documenting. Considering it was all new code to me, it took me no more than a few minutes to make the necessary changes to it to get it to work in my situation.
So while I have said before that to describe what good code is is rather difficult, my new definition for good code is any code which is discoverable and maintainable without resorting to documentation (because be honest, who reads the manual?) is good code. I probably should add it should also do what it's supposed to, but that's a given, no?
Without flattering Mr Kelly too much, JclExprEval fits that description perfectly. Now, back to the awful code that I was labouring with on Friday, which certainly doesn't fit that description.
Posts
3 comments:
A lot of conditions must be present, in order to produce code that is very easy to understand for the reader. Two of them are:
1) The reader's and writer's skills are matching.
2) The reader's and writer's personality types are matching.
The last point is significant. Some people prefer examples in order to understand code, others want to know the purpose or general idea in the code. To me, documentation of code is to make sure, that all of these are present, so that all kinds of readers can read it easily.
Everybody interested in "good code" development should have a look at Robert C. Martin's "Clean Code: A Handbook of Agile Software Craftsmanship".
ISBN-13: 978-0132350884
Incidentally, I just needed something like JclExprEval. After reading your posts about it and deciding to give it a try, I have now integrated it into my C++Builder application, and it works perfectly.
As you say, the code is very easy to follow - although I admit that I read the documentation first :)
However, this unit could benefit from anonymous methods.
Post a Comment