Showing posts with label Documentation. Show all posts
Showing posts with label Documentation. Show all posts

Wednesday, 9 May 2007

Commenting Code

Commenting code is something that all programmers, especially the students and newbies, are constantly reminded to do.

But how do you best go about it, and more importantly, how do you know when to add comments? Steve C McConnell says a good place to start is with good code:


Good code is its own best documentation. As you're about to add a comment, ask yourself, 'How can I improve the code so that this comment isn't needed?' Improve the code and then document it to make it even clearer.


The worst code i've seen would not have been helped by adding comments. The code itself needed to be drastically changed.

Code which has a logical structure and meets the requirements of Obejct Orientated design can often be worked out. It is when the programmer him or herself does not know what the class is meant to be doing that problems arise.

So sort out the code and comments will naturally follow.

Friday, 30 March 2007

Table Of Contents

In the voice of usefull information it is I write this post.

Programming is the name of the game. However there are often those nigley jobs that have to be done. Those secondary, even tertiary tasks that are small, unlikable and unavoidable.

It is in this manner that I hope to make the lifes of everyone who has to write a report that bit easier.

The contents section at the beginning of any report is always best left done to the end. Before i knew this feature of Word, I hated doing this. Every section removal, chapter addition or page change would lead to a slog to the contents section to make sure that everything else matched.

Alas it was pointed out, as is now to you, that Microsoft Word has a nifty feature of generating Table of Contents automatically for you.

Here's how you do it.

Step 1 Go through your document and give each chapter heading you want to appear in the contents a style format h1. Thats right, select the text and go to styles. From there just chose h1.

Step 2: Now inside every chapter, if there is important bits that you also want to appear in the contents, select it and style it with the h2 format.

Step 3: At the page you want to insert the table, choose Insert > Reference > Index and Tables. Click on the Table of Contents tab and then click OK.

Step 4: Edit it to your hearts desire. If you had made changes to the document and the contents is not reflecting this, press F9 for options on updating and editing it.

There you have it. My first usefull information post. I had to give in a report today and this was most useful. Now for you rascals who don't know this get back to work and give me ten lines.

'Insert > Reference > Index and Tables'
'Insert > Reference > Index and Tables'
'Insert > Reference ......'