Sections of This Page are:

• C Programming:
• Commenting Code:
• Creating Documents:

This page is for various other topics, not covered in other pages. It is likely that this page will cover a broad range of topics over time. Anything that does not fit elsewhere will go here.

Programming in languages other than BASIC and Assembly language will be on this page. This includes C, Pascal, and others that are outside the main topic of this site. There maybe others not yet thought about as well.

There will also be covered algorithm description languages, as these are important as well. This will include Flowcharting, and other diagram based descriptions of algorithms. Then there are the more written descriptions like Pseudo Code in its many forms. The ways of describing algorithms in a language neutral manner is important, as these algorithms are useful among many programming languages.

When we look at the details of a programming language, we must describe these languages in some way, this is the domain of a Syntax Description language. These include things like BNF, EBNF, WSN, etc, the formal Syntax Description languages. A programming language definition may also be represented in Syntax Diagrams, for some these are easier to follow than the formal description languages, and syntax diagram is just as capable of describing all of the language structure. It is important to understand the syntax description of a language, as it gives a formal set of rules for the syntax of a given programming language, which is important when using a language as well as when writing a parser for a given language.

It is important to understand how to create documentation for everything we create, from the code to the user documentation, to tutorials and such. Thus there will be some helpful guidelines covered on this page and subpages, with the goal of making it easier to provide better quality and more complete documentation. The lowest level of documentation is the comments contained within the source code, these must be of good quality and quite accurate, while keeping it terse. Then there is the larger body of documentation, including things like user manuals, how to docs, tutorials, and more. Providing good documentation is likely one of the most important aspects of any good program, or other software, that is going to be distributed in any manner.

All sections that end up on this page will grow to the point of having multiple sub pages linked in. This is a result of the amount of information making it unreasonable to represent completely in a single section, or even on a single page. The hope is that the information will be more easily accessible as a result.

NOTE BEFORE START : It is a bit surprising that C is not as easy to compile as one may expect, largely do to the long list of operator priority and ambiguity of declarations involving pointers.

C is a very capable High Level Programming Language (HLL for short) that lets the programmer do as they need. This makes for a very enjoyable experience in programming in C, in ways that one would have to experience to understand. It is largely do to the simplicity of C that it is capable and enjoyable, C is an extremely simple language at heart. With Indirection implemented in a very intuitive manner, using 'Pointers', the ability to manage memory and variables is without any limits whatsoever. This makes C an extremely useful language, beyond limits in most regards.

C is an extremely concise programming language, without any extra redundancy in the core language. Within C there are only 32 keywords to implement all statements, types, and structures, exactly what is needed nothing more. Within expressions there are 45 operators with 15 levels of priority, providing for a rich set of operations in a concise language. All of this makes C a very easy to learn language, being possible to learn the core language in a single day of concentrated study (so long as you already understand indirection), or a week of casual study.

There are a standard set of extra functions that C compilers are supposed to come with in the C Standard Library. These functions are supposed to improve portability, though only provide for text user I/O. The C Standard Library is not as useful anymore for Desktop, Palmtop, or Laptop computing, as most of these rely more on Windowing and other graphical output, amd mouse or touch screen input. That said the C Standard library can be helpful for some things, especially the math, string, utility, memory, date/time, and reference parts of the library.

Despite what many seem to think, modern C programs are not truly portable. Most modern programs use a Window manager and/or a graphics as well as mouse or touch screen input. Many try to use a ToolKit to get around this issue, though the toolkits are generally only useful on a few platforms, neglecting the rest, and they may be updated in incompatible ways. If portability is required the only way about it is to have a seperate source module that is target specific and provides a set of functions that implement the needed UI functionality and can be rewritten for different targets. There is no way to make C programs portable in a completely reliable way, this is a fact that we must live with.

C is a very capable language without limits, especially when used on a specific target OS. The C language is capable of doing many things that most people would not expect it to be able to do, sometimes to the amazement of many. Even OO can be implemented in C, yes it is possible to have Objected Oriented code implemented usefully in the C language without too much effort. C is a very much more capable language than most will give it credit for, especially when projects are targeted at a specific Operating System.

Unlike the native 680x0 API, the API for PowerPC native software on Macintosh System Software is the C Fast calling convention, making C a good language on the PowerPC Macintosh. The choice of API for the PowerPC Macintosh is a bit interesting, as it could do better than the 680x0 using a Pascal fast calling convention. That said the PowerPC Macintosh System Software improves on the 68K System Software in many ways, getting rid of a lot of the short sighted decisions of the original version when running PowerPC native.

Future Sub Pages will Include:

• An overview of C : Quick Look at Simple Langugae.
• C by Toy Example : Toy Examples, well documented.
• Pointers, where in memory do we go : Indirect needed in any language, C pointers are good example.
• Into Void, the non datatype datatype : Sometimes a nothing type can be useful.
• C Calling Conventions : A low level look at calling functions.
• Using C on RISC OS : void Pointers are a must here, as are union types.
• Macintosh Programming in C : Both harder and easier than you expect.
• OO in C : Yes Object Oriented programming in bare C, it is actually quite simple to achieve.
• Specific Examples in C.: More examples of C programming.
• Compiling Subset of C : Fun playing, and more by example progress.

FOOT NOTE : For such a simple language, I am surprised that I do not seem to use C as much as I would expect to.

When commenting code you must be careful to not allow comments to get out of hand. Remember to be concise in your wording for all comments. Though you must not be to short either, they must still describe what is needed. Make sure that your comments remain clear, while being concise.

Make sure to include your thinking in the reason for the method of implementation chosen. Why did you make the choices in how things are done, this may be more important than you think at first. If a algorithm is used that may not be normal it will help to describe the algorithm, at least in a brief form. Always take care to be clear and complete enough.

When writing any procedure or function, include a block comment before the definition that gives a bit of information about the function or procedure. This should include information on any parameters, as well as on any return values. It is also important to document any side effects of the Procedure or function in the comment block for that definition. Do not forget to include notes on the usage of the Function or Procedure the comment block belongs to.

It is possible that you may need the comments to help yourself remember how you did things in the future, maybe even in only three months time. You would be surprised what you might forget, especially if you write a lot of code between the initial creation and an attempt to update. It is important to you as well as anyone that may maintain the code base in the future.

When writing documentation you must first be clear on the intent of the documentation you are writing. Make sure to fully understand the reason for the document you are creating, and thus its usage. Remember that others may need more than you do to understand what is being communicated by your documentation.

As the next step it is best to write an outline of each part of your documentation. Make sure that your outline is done in parts, so it can be broken down as you continue. Continue to refine the outline into smaller parts until it has a quick reference for every sentence, and go from the outline. The outline will help to make sure you are clear in the presentation of what you are writing, thus improving the quality of your documentation.

For example the outline for this section of this page is: