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

[guinness]

I know the topic is pretty dumb, but am curious as to how people structure their comments in regards to appending a full-stop or not?

From the beginning of my AutoIt "career" I used to write comments like...

; This is a simple comment.

But since moving onto other languages I have adopted the style of not appending a full-stop at the end of a comment line.

; This is a simple comment

Why? Well I think it looks pretty and saves me typing one more character which is never a bad thing.

Edited July 15, 2015 by guinness

[JohnOne]

  On 7/15/2015 at 7:32 AM, guinness said:

 

They seem identical.

Did you forget to append a full stop?

Edited July 15, 2015 by JohnOne

[guinness]

Thanks @JohnOne, fixed it.

[JohnOne]

Looking at some of my code, it appears that sometimes I use . and sometimes I don't.

Not sure what it's related to, probably just my grammatical mood I suppose.

[Xandy]

WUT?  Don't ever let me catch you remarking without punctuation!

Outragious.

  Reveal hidden contents

$start_x = ($x - $player.iBoard_world_x) * $tile_w;       (oo)
$start_y = ($y - $player.iBoard_world_y) * $tile_h;      J UU L-====E
$end_w = (($w - $player.iBoard_world_x) + 1) * $tile_w;   {¥}
$end_h = (($h - $player.iBoard_world_y) + 1) * $tile_h;  _| |_

 

[Bowmore]

I still prefer to use the style of your first example with a space after the comment start characters and a full stop after the sentence. I use the full stop because that's the sort of guy I am, and the fact that I that I tend to use blocks of comment, to describe the what the code is intended to do, which may consist of several sentences.

[guinness]

OK, cool.

Good point, I never do this either:

;Simple comment in AutoIt
//Simple comment in C#

[jaberwacky]

I like to do certain things in my comments, but I hardly ever do them consistently. 

I make a distinction between documentation comments and code disabling comments.

I like to put a space after the semicolon and append a full stop to my documentation comments.  I don't put a space after the semicolon when I'm temporarily disabling code.

[jvanegmond]

Programming is hard enough as it is without meticulously watching your grammar in comments. They should be a quick way to show your thoughts as you were writing the code.

Why you're confused is that sometimes you do documentation of your code in comments. In C#, you can create neat summaries at the start of your function. You nearly always write those once the function prototype is complete and stable and you need to take your time to write it proper. Then you should also watch grammar.

[Nutster]

I tend to use complete sentences in my comments, including the appropriate punctuation.  So, periods show up at the end.

; Now for something completely different.
; Even though the last line (and this one too) are not complete sentences.

[Chimaera]

Bit of both for me i think

Prob more on the full stop than the other side

I write quite detailed ones as my memory is shocking

Edited July 16, 2015 by Chimaera

[guinness]

How complex is your code? Something like this, I would write maybe one comment, as the variables and structure are pretty easy to understand.

Local $sFile = 'ChromeEx.exe'

; Check if a filename is supported
Local $aSupportedFiles = ['Chrome.exe', 'Firefox.exe']
Local $bIsValidExe = False
For $i = 0 To UBound($aSupportedFiles) - 1
    If $sFile == $aSupportedFiles[$i] Then
        $bIsValidExe = True
        ExitLoop
    EndIf
Next

ConsoleWrite($bIsValidExe & @CRLF)

 

[JLogan3o13]

For me (and I would guess for most others) it depends on the audience. If I am writing something just for me, a one line comment like guinness has above would suffice to jog my memory. If it is something I am handing off, not only will I comment heavily (usually with full stops), but I will often break the script up using #Region. I just wrote a script for a customer to uninstall a product, and cleanup files/folders/and registry entries for all users. That one looks a lot like so:

expandcollapse popup

#Region=====================File System Variables============================
    ;Heavily Commented Code
#EndRegion==================File System Variables============================

#Region======================Registry Variables==============================
    ;Heavily Commented Code
#EndRegion===================Registry Variables==============================


#Region========================================File System================================================================
    #Region=============================remove user profile folders====================================================
        ;Heavily Commented Code
    #EndRegion=========================remove user profile folders======================================================

    #Region=============================remove system folders using dFOLDER array=======================================
        ;Heavily Commented Code
    #EndRegion==========================remove system folders using dFOLDER array=======================================

    #Region=============================remove single files using dFILE array===========================================
        ;Heavily Commented Code
    #EndRegion==========================remove single files using dFILE array===========================================
#EndRegion=========================================File System=============================================================


#Region==============================================Registry==============================================================

    #Region==========================================HKCR Keys===========================================================
        ;Heavily Commented Code
    #EndRegion=======================================HKCR Keys===========================================================

    #Region==========================================HKLM Keys===========================================================
        ;Heavily Commented Code
    #EndRegion=======================================HKLM Keys===========================================================


    #Region==========================================HKLM Values=========================================================
        ;Heavily Commented Code
    #EndRegion=======================================HKLM Values=========================================================

    #Region===========================================HKCU Keys==========================================================
        ;Heavily Commented Code
    #EndRegion=======================================HKCU Keys===========================================================
#EndRegion===========================================Registry==============================================================

Folding isn't exactly commenting, I know, and probably overkill, but I would rather that than someone calling six months later complaining I wasn't clear.

Edited July 16, 2015 by JLogan3o13

[AndyG]

Hi,

commenting code is one of my "vices". But i NEVER thought about to use a fullstop (at the end of a single line...)

Code must be "readable", including the comments. So i wrote a little script to align those comments, After pressing F4-key in Scite, the code looks (at least) good...  

This script could be expanded to put fullstops behind each Comment (or to erase them....)

 

Edited July 16, 2015 by AndyG

[guinness]

Of course when developing with other people, the level of comments is increased tenfold. I should have been clear that I was talking about comments in code you write for your eyes only and not in a team.

Edited July 17, 2015 by guinness
Fixed typos

[AndyG]

  On 7/16/2015 at 7:30 PM, guinness said:

I should have been clear that I was talking about comments in code you write for your eyes only.

Is there a difference between your eyes and mines?

Maybe after some years an application controlled by my (your) script is changed by an update. The script contains ...pfff.. 500 to 1000 lines. You have to look at the code and have to adapt it too. Do you think after some years there is a difference if you need to adjust this script, or I?

I don´t think so. I sometimes have to debug code written by other programmers. The time to debug/change code depends on the quality of the comments and their (visual) reference to the code.

 

  On 7/16/2015 at 6:12 PM, JLogan3o13 said:

For me (and I would guess for most others) it depends on the audience. If I am writing something just for me, a one line comment like guinness has above would suffice to jog my memory. 

Lucky guys.^^

I am too old. For my brain it is better to jog with other things...

[guinness]

  On 7/17/2015 at 5:18 AM, AndyG said:

Is there a difference between your eyes and mines?

I fixed a couple of typos in that last post. I would say so, as I have different style than you do. This is why we kind of have standards, so it's not such a huge learning curve for everybody.

[Chimaera]

This how i do it to answer your question

Local $sFile = 'ChromeEx.exe'

; Check if a filename is supported
Local $aSupportedFiles = ['Chrome.exe', 'Firefox.exe'] ; Files to search for
Local $bIsValidExe = False ; specify as a negative
For $i = 0 To UBound($aSupportedFiles) - 1 ; cycle through reducing, less 1 for the unbound
    If $sFile == $aSupportedFiles[$i] Then ; if file exists then
        $bIsValidExe = True ; set as true
        ExitLoop
    EndIf
Next

ConsoleWrite($bIsValidExe & @CRLF)

Ive just roughed this as its not my code but you get the idea.

I wish i didnt have a shocking memory but thats life ..

If i dont notate in  a months time i cant remember what the hell it was doing , prob why i ask so many questions lol

Edited July 17, 2015 by Chimaera

[mLipok]

I would like to add my 2 cent:

Local $sFile = 'ChromeEx.exe'

; Check if a filename is supported
Local $aSupportedFiles = ['Chrome.exe', 'Firefox.exe'] ; Files to search for
Local $iLastFileIndex = UBound($aSupportedFiles) - 1 ; check for last index in array
Local $bIsValidExe = False ; initialization - specify as a negative
For $iFile = 0 To $iLastFileIndex ; cycle through reducing, less 1 for the unbound
    If $sFile == $aSupportedFiles[$iFile] Then ; if file exists then
        $bIsValidExe = True ; set as true
        ExitLoop
    EndIf
Next

ConsoleWrite('$bIsValidExe = ' & $bIsValidExe & @CRLF)

 

[BrewManNH]

I only heavily comment code if what I'm writing can't be figured out by the average coder. I may put a small snippet of comments in the code if it's for myself. Generally, if you need to over comment your code so you're able to follow it 6 months later, you're writing bad code. As for punctuation in the comments, I may put them if I think of it, otherwise who really cares if you put a period at the end of it?

Edited July 17, 2015 by BrewManNH
typo