Friday, October 26, 2012

Code Complete: High Quality Routines

So reading Steve McConnell's Code Complete chapter 7 on writing "High Quality Routines" I am struck that there is lots and lots of great advice in there about writing methods.  Particular things such as clear naming conventions, relatively short routine length, short sets of input parameters etc. are all excellent.  However the problem that I have with the chapter overall is that it feels like it is easy to read it and then not put much of the advice into practice.  While the chapter has lots of great example code snippets, I feel like it is easy to ignore the great advice, given that it's not being encountered as part of a larger project.

Maybe this is just me.  I'm a huge fan of working on things in a larger context, but I know that that's not everybody's cup of tea.  It has been argued that some people like to read the abstract theory associated with things before encountering examples in context.  If you're one of these people please do get in touch and let me know.  I'd like to learn more about your thought processes.

Anyhow, just as an example of some mixed routine practices from things I was programming today, I created one short routine
and grabbed another from StackOverflow:

http://stackoverflow.com/questions/8240637/javascript-convert-numbers-to-letters-beyond-the-26-character-alphabet

Now I've got a really awful vanilla name for the routine I created (processForm) and all sorts of hacked together pieces of things, but that's partly a reflection of the "tracer bullet" methodology I was working on here, which was to get something that would take a form submission from a Google App Script generated html page, and enter the resulting data into a spreadsheet as described in this StackOverflow post:

http://stackoverflow.com/questions/13086880/can-i-mix-jqueryui-and-google-app-script-form-submissions

At least I can be pleased that both routines are relatively short and have a very small number of input parameters.  I think that both could be improved with refactoring.  I'll present that in a future blog post, but right now I know I and my students are going to be using this code every week to support assignment submissions, and getting a feel for getting this working in Google App Scripts was the top priority that trumped every other consideration.  Not the best programming practice perhaps, but let's see how I can iterate and improve this over the next few weeks.

Google App Scripts really rocks, but I'm still trying to work out how to version and share all this stuff effectively so we can see the software engineering and systems analysis issues in the context of this larger project, as described in this other SO post:

http://stackoverflow.com/questions/12712593/should-google-app-scripts-be-stored-in-version-control-like-github


2 comments:

Sasahara Shohei said...

> "Maybe this is just me. I'm a huge fan of working on things in a larger context, but I know that that's not everybody's cup of tea. It has been argued that some people like to read the abstract theory associated with things before encountering examples in context."

I am not sure if I am the one who really likes to read textbooks and understand theories before actually moving my hands and writing codes, rather than jumping onto it by doing actual exercises and so on, but I thought the reason why some people like to 'read the abstract theory associated with things before encountering examples in context' is because they can be confident about the new thing that they are about to do by understanding some of the things that masters, teachers, or even professionals, who have experienced and know a lot about it, think are important in advance. Being able to understand and have a visualization of what this thing looks like in their head allows them to have confidence and familiarity of the new thing, and I guess that is the option that they think is the shortest way to fully comprehend the material of it and eventually make use of it. I do not know, I can say these things maybe because I was the one who liked that way.

Sam Joseph said...

Hi Shohei, thanks for your great comment. I ended up not quite sure if you were one of the people who really likes to get the theory up front or not, but I agree there are definitely some people who do. For myself I find it really difficult to stay focused on a theoretical textbook. I just have trouble carrying on reading and staying awake if I can't relate things to a problem in the outside world. I guess there are some people who like to be fully equipped with theory before trying anything, but I'm often skeptical of established theory. Also I believe that the key skill to develop is how to cope with those situations when you are confused or not sure. One approach is to spend lots and lots of time reading in advance, but I would much rather run into the actual problem and then start looking for answers - trying to manage my fear of being stuck, and focus on how to effectively search and ask for help. It seems to me that that is the critical skill these days ...