Geeks With Blogs
AJ Warnock This Page Left intentionally Blank

Wow, it is only day two, and I am already drawing a blank?  Well, I believe that anything worth doing well is worth doing, right (sic)?


I think that at least for a while I will try to post at least once a week on Friday.  This at least gives me some time to actually be useful.  But for today, since it is Friday, I will improvise.


Yesterday, in a discussion with a co-worker and friend, I mentioned the term “Self Documenting code”.  His reply: “what do you mean?”  So, alas, out comes the Soap Box (that is similar to the “Don Box” only with shoes on and no little lollipop interfaces sticking out of it).  Sorry, I digress. 


Self documenting code is a topic that is far more important today than many developers’s ever desire to believe.  I am not talking about simply commenting your code and using the HTML help generation provided by the latest .Net development tools.  I am talking about truly writing code that you can go back in a month or even a year and know exactly what is SUPPOSED to be doing!  Regardless of the comments, the language or the complexity of the algorithm used, you should be able to determine what the code is supposed to do without any external documentation.


As software engineers and developers I believe than even the worst developer can eventually figure out what the code is currently doing.  However, how can we write our code so that we can understand what it was supposed to do while still keeping it reasonably maintainable and minimizing the impact on performance and size?


I know we call it “code” for a reason; however, that was from the days when we had no choices in syntax, formats and limited choices in languages (Yes, I still have code listings written using Fortran-77 and RPG).  As many developers in the last few years learned, cryptic code is not a source of job security those who create it.  It is only a source of frustration, anxiety and temporary job security for those of use who must clean up the mess.


This concept becomes increasingly more important as we generate code with tools that allow us to write thousands of lines of code.  With the new code generators and tools that all of us are beginning to use and write, we need to remember that we have to still read, understand and debug the code generated.  Shouldn’t this code be even more easily understood, efficient and at least as good quality as the code we write by hand (hey, I think there are a couple of other ideas for entries in there)?


So, how do we write self documenting code?  You decide.  After all this is only a BLOG.



Posted on Friday, January 20, 2006 7:41 AM | Back to top

Comments on this post: Day two and I am drawing a blank...

Comments are closed.
Comments have been closed on this topic.
Copyright © AJ Warnock | Powered by: