Good documentation increases the value of your programming. It allows other people to dive into your source code, and that is highly valuable both when key people are hit by disease, when someone leaves the company - and also if you ever want to sell your system to another company once you lose interest in furthering a specific project. It will allow others to continue without having to dissect what each procedure does. It is a highly powerful tool often overlooked by many technical nerds.
I will be dealing with internet programming - or webside coding - in the second lesson. I will be dealing with apps in the third lesson, but right now we will look at the fundamentals of programming. In the sense of creating a program that is to run on a computer under an operating system like Windows, MacOS or Linux.
No matter what system you are running, there are various programming languages. In this lesson we will look at the general concepts relating to programming...
A programmer creates instructions that a computer can repeat every time you run the program. In the old days, such programs were line-based. In a language such as BASIC or COMAL - used in many schools back in the days of DOS (prior to Windows becoming a stand-alone operating system), you started with a line number, and then you wrote your program.
If you discovered that you needed to insert code, you could RENUMBER those lines, and therefore get an opportunity to insert up to nine lines of code, and then you had to renumber again - and you quickly discover this could become rather time consuming.
When a programming language such as Pascal (most popular was Turbo Pascal by Borland) came on the scene, you could begin to work with procedures.
When you needed to create a phone book, you could have a procedure for peeking into the phonebook, one for adding contacts, one for deleting etc. Nowadays, we would just create a database in Access or maybe a spreadsheet in Excel. :-)
Procedures allowed to add complexity to programming, but also the ability to plan your procedures. Things you had to do multiple times could be put into a procedure, and then called by another procedure as you needed that specific functionality during another manipulation of data.
The problem about such complexity is that some programmers had very poor discipline - both when it came to documentation but also in giving names to each procedure. They could indeed create a program that worked, but when you had to make changes to that program a couple of years later, no one could see how it was all created. In some instances you had to begin from scratch because of such situations...
This is why documentation is so important. Good documentation involves the following:
Use sensible variable names - namecustomer is better than name because you might also need a name for a supplier, and thus you end up with name, name1 etc if you're not mindful of this.
Give procedures a good name - it is quite logical that xyz tells you less about what the procedure does than update_calendar.
Explain what the procedure does - when you have many variables in a procedure, it's important that it is explained in the documentation.
Bear in mind that once you COMPILE your program, which means converting it into an executable file, comments are not compiled into the program. You could therefore easily have a megabyte long source code file that compiles into an executable file that is much smaller. This is the same with variable names. This is handled automatically by the compiler, so you won't end up with larger files just because you begin implementing good documentation...
What you WILL get is quality that you can maintain and get back to many years later.
Stay tuned for lesson 2 on programming. :-)
No comments:
Post a Comment