Whatever happened to …

… internal documentation?

On a typical day, it’s not uncommon to have to update applications or operating systems or drivers or whatever on your computer.

it’s a fact of life and good computer users who want their software to be running the latest and safest will do it regularly.

But, think of the programmer that works to make these updates available.

Do they turn on their computer and look at a bunch of code in whatever language the update is written in and read everything from top to bottom and understand every step, every procedure, the purpose of every variable, etc. every time they have to update the code?  What if you’re on a team and there are a number of other programmers?  How do you know what your colleagues are doing?  

It would be a pretty tedious job if they did.  And, what if the original developer and holder of the information has left the organization?  Does the subsequent author have to learn from scratch?

Of course not.  Crucial to this is internal (and external) documentation of the program.  A good piece of software is like a good story.  It’s well written, documented, and described.  Check these out.

http://www.htmlist.com/development/the-bane-of-documentation/

http://www.cs.ecu.edu/karl/3300/spr14/Notes/Documentation/documentation.html

So, every programming language has the ability to do this?

Not so quick.

Take a look at one of the more popular first coding platforms – Scratch.  It is very powerful and designed to make things easier for the developer.  Yes, students are developers in their own right and at their own level.  The Scratch website allows for the resharing and repurposing of code and good contributors will have a good description of how the code works.  But, internally?  

What programmers refer to documentation is an entire different story.  Pick up someone else’s code or revisit something that you’ve written in the past and you’ve got to read it at times like you’re reading it for the first time.  It’s so inefficient and inconsistent with the principles of good coding techniques.

And yet, we promote this with the intent of getting students involved in coding for their first language.  How many times do we hear that Canada doesn’t have enough programmers so we need to develop them now?  Scratch and similar languages are the launching pad and yet it doesn’t support the internal documentation that will be required later should these programmers decide to take it seriously.

What are your thoughts for a Sunday morning?

• How do you have your students document their coding and their thinking?
• Have you ever revisited code of your own and have no idea how it was constructed?
• What are the techniques that the beginning coder should have to guarantee success?
• At what point do students need to learn about internal documentation if their first language doesn’t support it?
• Is it possible to “over document” a piece of code?

Please share your thoughts in the comments below.

Check out the entire collection of Sunday morning memories here. And, if you’re so inclined, through a suggestion in the Padlet.