Sign in to follow this  
Followers 0
Morthawt

Any comments on comments?

22 posts in this topic

#1 ·  Posted (edited)

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 by Morthawt

Share this post


Link to post
Share on other sites



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.


If I posted any code, assume that code was written using the latest release version unless stated otherwise. Also, if it doesn't work on XP I can't help with that because I don't have access to XP, and I'm not going to.
Give a programmer the correct code and he can do his work for a day. Teach a programmer to debug and he can do his work for a lifetime - by Chirag Gude
How to ask questions the smart way!

I hereby grant any person the right to use any code I post, that I am the original author of, on the autoitscript.com forums, unless I've specifically stated otherwise in the code or the thread post. If you do use my code all I ask, as a courtesy, is to make note of where you got it from.

Back up and restore Windows user files _Array.au3 - Modified array functions that include support for 2D arrays.  -  ColorChooser - An add-on for SciTE that pops up a color dialog so you can select and paste a color code into a script.  -  Customizable Splashscreen GUI w/Progress Bar - Create a custom "splash screen" GUI with a progress bar and custom label.  -  _FileGetProperty - Retrieve the properties of a file  -  SciTE Toolbar - A toolbar demo for use with the SciTE editor  -  GUIRegisterMsg demo - Demo script to show how to use the Windows messages to interact with controls and your GUI.  -   Latin Square password generator

Share this post


Link to post
Share on other sites

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.

My UDFs and Tutorials:

Spoiler

UDFs:
Active Directory (NEW 2017-04-18 - Version 1.4.8.0) - Download - General Help & Support - Example Scripts - Wiki
OutlookEX (NEW 2017-02-27 - Version 1.3.1.0) - Download - General Help & Support - Example Scripts - Wiki
ExcelChart (2015-04-01 - Version 0.4.0.0) - Download - General Help & Support - Example Scripts
Excel - Example Scripts - Wiki
Word - Wiki
PowerPoint (2015-06-06 - Version 0.0.5.0) - Download - General Help & Support

Tutorials:
ADO - Wiki

 

Share this post


Link to post
Share on other sites

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.


"Programming today is a race between software engineers striving to build bigger and better idiot-proof programs, and the universe trying to build bigger and better idiots. So far, the universe is winning."- Rick Cook

Share this post


Link to post
Share on other sites

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.

1 person likes this

AutoIt Absolute Beginners    Require a serial    Pause Script    Video Tutorials by Morthawt   ipify 

Monkey's are, like, natures humans.

Share this post


Link to post
Share on other sites

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 :P):

;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.


[center]Spiderskank Spiderskank[/center]GetOpt Parse command line options UDF | AU3Text Program internationalization UDF | Identicon visual hash UDF

Share this post


Link to post
Share on other sites

#9 ·  Posted (edited)

#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 by Decipher

Spoiler

censored.jpg

 

Share this post


Link to post
Share on other sites

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.


~ WhiteStar Magic

Always tuned to http://www.superbluesradio.com/  Tune in at http://87.117.217.41:8036/

Share this post


Link to post
Share on other sites

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.

[center]Spiderskank Spiderskank[/center]GetOpt Parse command line options UDF | AU3Text Program internationalization UDF | Identicon visual hash UDF

Share this post


Link to post
Share on other sites

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.

Share this post


Link to post
Share on other sites

#13 ·  Posted (edited)

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 by prcssupport

Share this post


Link to post
Share on other sites

#14 ·  Posted (edited)

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 by JohnOne

AutoIt Absolute Beginners    Require a serial    Pause Script    Video Tutorials by Morthawt   ipify 

Monkey's are, like, natures humans.

Share this post


Link to post
Share on other sites

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

Share this post


Link to post
Share on other sites

#16 ·  Posted

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!

Share this post


Link to post
Share on other sites

#18 ·  Posted

Thanks for your reply , @czardas

1 person likes this

Share this post


Link to post
Share on other sites

#20 ·  Posted

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

 


,-. .--. ________ .-. .-. ,---. ,-. .-. .-. .-.
|(| / /\ \ |\ /| |__ __||| | | || .-' | |/ / \ \_/ )/
(_) / /__\ \ |(\ / | )| | | `-' | | `-. | | / __ \ (_)
| | | __ | (_)\/ | (_) | | .-. | | .-' | | \ |__| ) (
| | | | |)| | \ / | | | | | |)| | `--. | |) \ | |
`-' |_| (_) | |\/| | `-' /( (_)/( __.' |((_)-' /(_|
'-' '-' (__) (__) (_) (__)

Share this post


Link to post
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!


Register a new account

Sign in

Already have an account? Sign in here.


Sign In Now
Sign in to follow this  
Followers 0