How do you write comments in your source code? With a full-stop or without?

[Skysnake]

a good buddy who is qualified engineer, programmer and project manager tells me he has seen meetings break up as to 'how to properly make flower boxes' --- i guess that programmers are highly individual lot and very opinionated... this makes it very difficult to agree on a 'standard' - never mind 'best practice' or even a 'single best way' to teach new coders (ie AutoIt or anything else for that matter).

I have found that I use a kind of shorthand.  I have several small projects running to automate all kinds of silly little things in my office, which save massive amounts of time, and I have learnt the hard way that without comments the first time round, the updates kill me, because what seemed painfully obvious initially, may not be so clear a year from now.

this is not a silly topic, but a potentially hazardous one

*****************************************************************
* not a programmer, but a keen auto-mater                       *
*                                                               *
* hoping to avoid a flame war.                                  *
* :)                                                            *
*****************************************************************

in any event, some examples and recommendations in the FAQ on comments may also be a good idea. even if not everyone agrees, at least it will present a starting point...  

 

[czardas]

I have given up thinking about this and started writing all my single (EOL) statements using lower case without full stops - like in a list. If it requires more than one sentence, then I would probably create a comment block and write normal English.

Func _OverflowDetect($sOperator, $iOperand_1, $iOperand_2)
    If Not StringRegExp($sOperator, '\A\s*[\+\-\*]\s*\z') Then Return SetError(1) ; operator not recognized
    If Not StringInStr(VarGetType($iOperand_1), 'Int') Then Return SetError(2) ; meaningless request
    If Not StringInStr(VarGetType($iOperand_2), 'Int') Then Return SetError(3) ; ditto

    ; execute the expression
    Local $iExecute = Execute($iOperand_1 & $sOperator & $iOperand_2)

    ; execute the expression with the operands converted to doubles
    Local $fCompare = Execute('Number(' & $iOperand_1 & ', 3)' & $sOperator & 'Number(' & $iOperand_2 & ', 3)')

    ; the results should be approximately equal
    Return StringFormat('%.15e', $iExecute) <> StringFormat('%.15e', $fCompare)
EndFunc

 

Edited August 29, 2015 by czardas

[guinness]

I try to avoid comments after a statement these days and opt for placing on a separate line. Browsing around, I see more people adopt your approach @czardas.

[czardas]

For me, whether to write a comment at the end of a statement depends on how long the line of code is and also consistency of layout. I don't think you can generalize about this. The important thing is that it is easy to associate the section of code that a comment refers to. My reason for not using capitals is my own attempt at consistency: 'ditto' is not a sentence. I got fed up with mixing and matching sentence case. I think it looks rather messy when sometimes a capital appears and at other times not.

Edited August 29, 2015 by czardas

[guinness]

General standard is 80 characters wide. Why that is (after I did a bit of research) is a salute to the old days. Silly if you ask me.

Edited August 29, 2015 by guinness
Typo

[czardas]

You learn something new everyday.

[guinness]

I have known it has been 80 for ages, but I prefer 120 OR I don't care =) Just didn't know where 80 came from as it's seemed an arbitrary number to me.

[Chimaera]

I generally go on the line straight after the code because underneath makes the script huge well the amount i add anyway.

So just a few words at the end works for me.

The examples on separate lines are prob easier to read but i guess you adapt your own style

[jvanegmond]

I have known it has been 80 for ages, but I prefer 120 OR I don't care =) Just didn't know where 80 came from as it's seemed an arbitrary number to me.

We have rules for this where I work. We went from 80 initially to 120 now which is quite a lot. You need to consider information density per line. Only so much will fit in your brain. Clear and short lines are best.

[guinness]

We have rules for this where I work. We went from 80 initially to 120 now which is quite a lot. You need to consider information density per line. Only so much will fit in your brain. Clear and short lines are best.

I think it can depend on the language, because in PHP 80 is okay, but for jQuery plugin it can sometimes be too little.

[mLipok]

I have known it has been 80 for ages, but I prefer 120 OR I don't care =) Just didn't know where 80 came from as it's seemed an arbitrary number to me.

80x60 chars on old monochrome CRT display

 

Edited August 30, 2015 by mLipok
added word "old"

[TheDcoder]

; I don't use fullstops in single line comments

#cs
But I do proper puntuation in multi-line comments, it looks neat too.
#ce

 

[TheSaint]

Basically for me, it can vary with comments, but generally I will end a comment with a full stop if I remember and it is not a title to a section. I also use a space for a text comment, and none for disabled code. I also use case differences for specific elements, especially to further differentiate titles. They all help speed up deciphering at a glance I find. I also use a lot of commented blank lines to help tie things together but allow for easier reading, along with specific indents. I use a lot of groupings to separate out types of code, etc. I'm guessing when others look at my code, they see a distinct pattern ... I certainly do. Readability is high on my agenda of good coding practices. To that end, I often spread commands over multiple lines, rather than have some single complicated looking line ... but that is sometimes governed by mood and surrounding complexity ... that means I sometimes simplify things to break things up for better readability. There is always a method behind all my coding, with simplicity of understanding my constant aim.

Like most I suspect, you develop a certain set of habits, early on, that you keep refining. You may occasionally make a leap that is a somewhat radical change, as your knowledge and experience develops. I have done so a few times. I can now date my scripts by their layout.

I also never use Block Commenting, as I find it doesn't stand out enough for me. And I rarely put a comment after code on the same line, except when I am being very descriptive, as an aid to others or when complexity is high.

; CONTROLS         (a title)

; SETTINGS       (another title)

; Title

; Not a title.

;$var = 1

P.S. Funny how a simple full stop can open a floodgate.

Edited September 8, 2015 by TheSaint

[BrewManNH]

Like most I suspect, you develop a certain set of habits, early on, that you keep refining. You may occasionally make a leap that is a somewhat radical change, as your knowledge and experience develops. I have done so a few times. I can now date my scripts by their layout.

I can agree with that, my old VBScripts used to use some very identifiable commenting so that anyone that had to try to figure out what I was doing would be obvious even to someone not that familiar with what I was doing in that section.

; ***************************************
;
;     Comment went here
;
;****************************************

As you went through the scripts, you'd KNOW that something different was being done in this section that was different than the last section you were looking at. I don't know if anyone had to follow the scripts I wrote later, but they sure knew what I was doing in the code when they needed to change something.

I don't make current comments quite so "bold" these days, but I still sometimes use that style when I have code that is something that could be moved to another script without modifying it.

Edited September 8, 2015 by KingBob

[OldGuyWalking]

I know I'm very late to this topic but it is an interesting one.  I've been writing code since the days of the Commodore 64, mostly in BASIC then a couple of decades later I started coding MS Office apps in VBA.   Self-taught for the most part until I took courses in Cobol and then eventually C (which I never moved forward with because I could never get my head wrapped around pointers).  Even in the early days, documenting code was something that came up in courses, articles, and from users in user groups who were developing applications. 

In the early days of BASIC there wasn't alot of bandwidth or storage space available so code was usually written with very few comments and the comments that were in the source code tended to be very short to save space.  It also made the comments cryptic. 

As space became less of an issue comments became longer but after a year or two most of those comments became cryptic.  I got into AutoIt in 2008 and put together some scripts that I used at work and some at home.  I wrote scripts in AutoIt until about 2013 and only picked it back up a few months ago.  I happened across some of the scripts I wrote in 2008.  It was like reading code from someone else. Some of the comments in the code made sense and some of them fell into the category of "what was I thinking?".

Anyway, I have done some online tech writing for some really tough editors.  I tend to write the way I think but when writing articles for a general audience there must be consistency in the writing style and a reasonable attempt at cleaning up grammatical, spelling, and punctuation errors.   

However, for programming, I don't write comments for an audience, I write them for myself.  If I ever had any generic code that might be useful to anyone other than myself I would probably make an attempt at making the comments clearer or even expanding them.  I'd probably even add a period at the end of each  sentence. 

But for now, my goal is to write a comment that will not only make sense to me now but will also make sense to my future self. Punctuation is optional and spacing and indenting is whatever my fingers happen to feel like doing when I'm typing the comment. 

Generally, my comments are above any section of code that I believe could require some explaination at a later date.  I may comment Dim'd variables on the same line as the variable.  If I have a group of variables such as the variables used in a GUI form or column names in a Listview then I'll have a one line comment above the group identifying what the group is associated with. 

I also tend to add lines, boxes, asterisks, <--- arrows, etc. over any code that I consider to be important or when I know I'm going to want to make some additional changes to the code at a later date.  If I have working code that I can reuse later in another project or can add to my Include file I will add a comment above and below the code and include the words  "Recycle Code".  Then, when I have the time to work on consolidating code I can do a text search through the *.au3 files to get a list of any code I haven't worked on yet.

It's one of the nice things about au3 files being text.  It makes them easy to search.

Edited June 16, 2016 by OldGuyWalking
Additional random thoughts...

[czardas]

I quite often use raised eyebrows in my comments:

; ^^

. . . simply to draw attention to a particular line of code. I've got used to doing this now and anyone reading the code is likely to figure this out before long, or at least ponder the importance of an expression a little while longer.

Edited July 4, 2016 by czardas

[TheDcoder]

; ^^

 

[czardas]

Related Article: http://blogs.msmvps.com/benvoigt/2009/08/01/technical-documentation-like-code-does-not-follow-english-rules-for-grammar-and-style/