Any comments on comments?

[Morthawt]

I hardly ever comment my work. It does come to bite me in the backside because weeks later or even days later I cannot just "know" exactly what is doing what and why until I take the time to manually re-read and re-understand what I am doing.

Do you comment your scripts for clarity and understanding? If you do comment, would you say you use a lot of comments to where you almost have a written English description of what the script is doing OR do you only tend to comment certain convoluted areas that you assume would lead to future confusion of understanding those parts?

Edited November 17, 2012 by Morthawt

[BrewManNH]

I comment the HELL out of my scripts if they're not just a one off helper script. It helps in the future to know what that variable or function call is supposed to be doing. You can put a script away for months and still be able to work on it right away if you don't have to relearn what you did.

[water]

I do comments. I document in 3 places:

• Script: At the start of the script there is a header describing what it does, the parameter it expects, the result it returns and the error code
• Functions: Every function gets a header describing what it does, the parameters, the returned result and the error codes
• Area/Statements: If I do something that is not too obvious I add comments so I can understand what I've written next week or next year

But your mileage may vary.

[AdmiralAlkex]

The Coding Horror blog has a lot if interesting posts about coding style and commenting, for example Code Tells You How, Comments Tell You Why

[Bowmore]

My style for larger scripts is to start by writing it in the form of comments stating which processes need to be carried out in order to complete the task in hand. Most of these comments then become the description of what a function does. Within functions I keep my comment to a minimum by using clear descriptive names for functions and variables so that the variables largely self document the code as I write it. I try to avoid using multiple conditions with If, While etc. instead separating the checking of each test condition into a separate statement. This makes my scripts longer but generally I find it makes them easier to understand a year later. I only add extra comments in places where an error condition is returned and I have had to use some slightly obscure method where speed was critical or a workaround was required.

As mentioned in AdmiralAlkex post comments should tell you the why and not the what about your code. What your code is doing should be clear from just reading well laid out code that uses a consistent, clear naming convention. Avoid boilerplate comments except in the case when documenting how to use functions in a library that others will be using.

[JohnOne]

I very rarely add comments, opting for very descriptive function names and variables.

Yes, the use comments dog snaps around my ankles all the time, but I just ignore it.

I have found that it's not big and not clever, but I just don't like yapping little dogs.

For the record, I still advise people to use comments, and think it's wise to do so.

[dany]

Most of the time that's the biggest question when returning to badly commented code after a few months: Oh God WHY?!?

All my UDFs and applications start with a description, changelog and todo-list, makes it easier to keep track of things.

I comment code wherever I think it's necessary (which isn't always often enough ):

;TODO: Placeholder for fast searching of code that needs work.

Global Const $A_MAGIC_NUMBER = 4294967295 ; 2^32 - 1 Or how did I come to this number.
; Optimizing such calculations for Constants is a good idea but it's not always obvious where the number comes from.

Global $aGUI[100] ; Somewhere there will be a list of what index contains what kind of control, e.g. $aGUI[10] = Exit button etc.

; Math like this is rather obvious, especially when using descriptive variables.
$iAdjacent = $iOpposite / Tan($iDegrees / 57.295)
; But when the math gets more complex, I comment what's going on. Especially when the formula gets lost
; in the languages syntactic implementation. A good example by monoceres is the Moon orbiting Earth:
; http://www.autoitscript.com/forum/topic/81580-moon-orbiting-earth-gdi/
; Looks deceivingly simple but it's magic if you don't know the underlying math or can't derive the formula.

In general when the Why isn't readily obvious from the How of the code, I (try to) comment. Especially in the case of using copypasted code snippets (say from the Wiki) I always include the link to the post and if I modify the snippet, I always comment why.

[JohnOne]

Yes, that's something I do, link to the place where I took code or an idea if it's applicable.

[Decipher]

#region ### Script Area ###
; I tend to use regions with large scripts to fold parts up, makes for easier deciphering without the scrolling. :)
#cs
Use Globals,Constants,Includes,Functions,Internal Functions,Header - Regions

Anything else you can distinguish when writing large scripts helps.

Not human english persay but logical statements help to write code.
#ce
#endregion ### Script Area ###

Ctrl+Q Quick Comment your code in Scite.

Love the keyboard and hate the mouse - Famous Quote by Decipher

Edited November 18, 2012 by Decipher

[WhiteStar]

Another on the Comment the hell out of it group. I tend to stick to more descriptive naming conventions and sometimes will drop my pseudo code as I am thinking through the processes.. makes it a heap loads easier. Tidy it all up after I'm done writing it and leave in the important comments. While developing something, Id say my average is 20-25% +/- comment to code, cleaned about 10% maybe.

[dany]

Yes, that's something I do, link to the place where I took code or an idea if it's applicable.

Yea, especially when porting something to AutoIt from a different language. It's always fun to hit on something OO and try to bring it down again to procedural code.

[jmon]

I like to declare my arrays like this:

;$aArray:
;-----------------------------
;$aArray[0][0] = Number of rows
;$aArray[0][1] = Number of Columns
;$aArray[0][2] = Another value
;-----------------------------
;$aArray[n][0] = Item ID (Int)
;$aArray[n][1] = Item Price (Float)
;$aArray[n][2] = Item Order (Int)
;$aArray[n][3] = Item Available (Bool)
;$aArray[n][4] = Item Comment (Str)
Global $aArray[10][5]

With the comments above the array it's easy to remember which row / column is what.

[prcssupport]

Yes, that's something I do, link to the place where I took code or an idea if it's applicable.

That is something I'm going to have to do. I just spent several days, rewriting code I had found in the forum. Unfortunately I could not relocate it. Thankfully I was able to get it back. But I have learned I will start linking to it in the script.

I have so much learning to do. I have such dreams about code and things I want to do, and not enough time to get them written to code!

I'm still new to Autoit, So I comment more than most. It helps me be able to understand without spending alot of time reading it all. And checking definitions if I can't remember what the function does.

Prcssupport

Edited November 20, 2012 by prcssupport

[JohnOne]

I like to see a whole function in the edit control from Func to EndFunc which is mainly why I do not comment so much.If I cannot do that then I create another function so I can

Edited November 20, 2012 by JohnOne

[Morthawt]

I probably should get into commenting more often then lol. I do see the wisdom in it, just not in a habit of doing it at the moment. I do use the "-" key on my numeric keypad to do quick commenting similar to the Ctrl Q that was mentioned

[lillo78]

Kinda old thread but i didn't know where to ask this.

My question is: is it possible to comment like a single world? i mean, if i have a call to a function which has a lot of parameters i'd like to make a little comment right after each parameter, like this: myFunction (param1/*name of the user*/, param2/*user's address*/, param3/*user's age*/, and so....)

Just like we can do in Java and/or other languages,

is that possible?

Thnks in advance!

[czardas]

No, but you can frequently align comments on an adjacent line.

;.......... define 1, define 2
Func MyFunc($vParam1, $vParam2) ; general comments
    ; actions to do
    #forceref $vParam1, $vParam2
EndFunc ;==> MyFunc

 

[lillo78]

Thanks for your reply , @czardas

[czardas]

Or you can do something like this (which I think I prefer):

Func MyFunc($vParam1, _ ; define 1
            $vParam2)   ; define 2
    ; actions to do
    #forceref $vParam1, $vParam2
EndFunc ;==> MyFunc

 

[iamtheky]

I only get liberal with comments around loops, regex, and nested functions. 

my internal funcs tend to not need comments, because they look like this:

Func MyFuncThatDoesAThingBasedOff2Things($ThisThingDoesThing1 , $ThisThingDoesThing2)   
    ; Does thing based off those 2 things
EndFunc ;==> MyFuncThatDoesAThingBasedOff2Things