Proper Commenting with source code?

[win2k]

Im not a big programmer, in fact, I'm learning more about Autoit everday. I'm not a CS major, I am an MIS major with a concentration in networking, so my programming skills are weak at that. I am currently working on a program for a company that I work for and I want to make sure that I comment code in a professional manner. I have had to figure out code with very few comments and it is frustrating so I don't want to pass that off to anyone else that may edit the program I am making. Is there a good FAQ, document, post or any other helpful information on how a professional would go about commenting their code?

[BPBNA]

I usually divide it into sections

;This block of code does...
Code Here

;This block of code does
More code here

You can also comment the lines seperatly especially for longer more complicated ones

big-long-hard-to-understand-code here  ;This big-long-hard-to-understand-code does this

I'm no pro either, just use common sense. If you think someone may have trouble seeing what a block of code does, comment it.

[Valuater]

"Welcome to Autoit 1-2-3" covers this and proper formatting

( in my sig below)

8)

[Squirrely1]

Here is an example of how I comment the head of my User Defined Functions in AutoIt:

expandcollapse popup

; ====================================================================================================

; Name:             _StringPathCapable()
; Description:      Returns a valid full file path or folder path.
; Syntax:
;                   #include "Path.au3"
;                   _StringPathCapable($st_Pathname, [$s_Switch])
;                       e.g.: $myFolder = _StringPathCapable("C:\My >Docu/me*nts\Media\My Mo|vie.mwv")
;
; Parameter(s):
;                   $st_Pathname - Pathname of the folder or file to fix.
;                   $s_Switch - Flag as an integer that is the sum of:
;                           0  leave any trailing backslash or slash on the pathname if present (default).
;                           1  remove the trailing backlash or slash on the pathname if present.
;                           2  add a trailing delimiter ( "\" or "/" ) if not present (over-rides 1).
;                           4  replace all slashes with backslashes: ( "/"  ==>  "\" )
;                           8  replace all backslashes with slashes: ( "\"  ==>  "/" )
;                           16 replace all adjacent spaces with only one: ( "   "  ==>  " " )
;                           32 remove the enclosing quotes ( whether "'" or '"' ) if present.
;                           64 add enclosing double-quotes ( "sPathname" ) if neither type of
;                                   enclosing quotes ( "'" or '"' ) are present (can be used with 32).
;
; Return Value(s):
;                   Success: the passed pathname which was fixed if necessary
;                           e.g.: "C:\My Documents\Media\My Movie.mwv" )
;                       @Error is set to 0
;
;                   Failure: ""
;                       @error is set to -1 ( complete function failure )
;                       @error is set to -2 ( the passed string was no filepath )
;
; Note(s):
;                       Characters always removed by this UDF: * ? | > < ] [
;                           and any double-quote (") if not enclosing the whole string
;                           and all but the first ":" that appears in the pathname.
;                       Enclosing quotes of the apostrophe-type (') are removed if flag 32 is set, but
;                           no other instances of apostrophe's are ever removed by this UDF.
;                       The first folder delimiter found in the passed string will replace all others.
;                           e.g. if the first is "\" then all "/" will be replaced with "\"
;                       If path delimiters are backslashes "\" then no double backslashes will survive.
;                       Strings passed with quotes enclosing it will keep their enclosing quotes unless
;                           Flag 32 is specified.
;                       Might work for remote drives.
;                       Wildcard characters ( * and ? ) are stripped from the return value.
;                       Accepts relative pathnames, e.g.: "\Owner\Her Documents\"
;                       Leading and trailing whitespace and @CR are always removed by this UDF.
;
; Author(s):        Maxwell J. Clevett <maxwellclevett@att.net> & AutoIt team
; AutoIt Version:   3.1.11x + ( must be the beta for _StringReverse() )
; Example:
;                   #include <$myUDFDir & "\Path.au3">
;                   $myFolder = _StringExtractDirectory ( "\My Documents\Med*a\" )
;               ; $myFolder now equals "\My Documents\Meda"
;
; ====================================================================================================

Otherwise, it seems that in AutoIt we do make little notes about what the main parts of a module are supposed to accomplish. It can be helpful to keep track of the various sorts of variables you use, using comments. A variable that you have resolved should not change its value once one has been assigned one, you might comment that its value should never change. Also descriptions of what might later prove to be unexpected program flow control should be marked with a comment. If you create a function in your script that needs a particular #includes file, and you follow the convention of putting your #include "..." line at the front of your script, it could help to make a note in your function that that is one of the functions that requires that line in case you want to remove it later, to make your program use less memory. With SciTe, also, we have the element #Region myRegionName ... #EndRegion myRegionName which can help organize the beginning of your script into modules that are not functions, but which accomplish different ends. These do not execute and are like comments.