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.

 

Advertisements

2 thoughts on “Whatever happened to …

  1. There is a theory that code in languages like Scratch is so simply defined that it needs no documentation. I’m pretty sure I don’t agree that is the case for any really interesting code. I tell my students about a case where documentation in some code saved me from a lot of trouble. A program that was pretty basic that I thought I could reproduce from memory in a new language didn’t work until I went back to the comments in the original code (on a card deck).

    Liked by 1 person

  2. I came across a deck of computer punch cards this weekend. One of my favorite programs from my university days. I did a good job of commenting but a poor job of variable naming. At least with the comments I can understand what is going on. Checking toggle switches to control the program. I’d forgotten all about that. In any case I think I know enough now to improve the version of this old program that I’ve written in TouchDevelop. Alas my comments in the TouchDevelop version are not very good (ie. there are none) even though the variable names are better.

    Like

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s