How are you adding comment sections to your source ?

[va!n]

Maybe a litttle stupid but on the other hand interesting point... How are you adding comment sections to your source!? What kind of are you using!?

Code: Select all

Style a)

; =============================================================================
; =
; =    P r o c e d u r e s
; =
; =============================================================================

Code: Select all

Style b)

; /////////////////////////////////////////////////////////////////////////////
; /
; /    P r o c e d u r e s
; /
; /////////////////////////////////////////////////////////////////////////////

Code: Select all

Sytle c)

; *****************************************************************************
; +
; *    P r o c e d u r e s
; *
; *****************************************************************************

[Killswitch]

This is my standard program template. I change the second line to the program title (but in the same style i.e. ;\\-Program Name-----) and I also add other comments like so: ;\\Comment

It doesn't really add anything to the source, but it's just the way I do things .

Code: Select all

;\\------------------------------
;\\------------------------------
;\\------------------------------

 
;\\-Notes--
; Started:
; Completed:
; Version:
; Authors:
; Type: Program
;
;\\--------

;\\-Constants--------------------

;\\------------------------------

;\\-Structures-------------------

;\\------------------------------

;\\-Variables--------------------

;\\------------------------------

;\\-Includes---------------------
 
;\\------------------------------

;\\-Declares---------------------

  ;\\Misc
    Declare Error()
      OnErrorGosub(@Error())
  
;\\------------------------------

;\\-Main-------------------------
  

;\\------------------------------

;\\-Procedures-------------------
  
  ;\\Error

    Procedure Error()
      MessageRequester("Error",GetErrorDescription())
      End
    EndProcedure
  
;\\------------------------------

  End

;\\-End--------------------------

[Joakim Christiansen]

I made a screenshot to show how I like it... :

[traumatic]

[Joakim Christiansen]

good programmers don't comment their code. it was hard to write - should be hard to read!

I don't agree with you!

[PB]

> How are you adding comment sections to your source!?

I agree with traumatic -- I don't comment unless I really think I need to.
Anyway, for short comments, I usually add to the end of a line or command:

Code: Select all

Sleep_(1) ; To not use 100% CPU.

If the line has several commands, I usually comment whatever is relevant:

Code: Select all

w=WindowWidth(0)+pgw : h=WindowHeight(0) ; pgw = PanelGadget width.

If a whole line needs commenting, or if the comment is long, I usually
comment the line above it:

Code: Select all

; Next line resizes the window to match the PanelGadget height.
w=WindowWidth(0)+pgw : h=WindowHeight(0)

If a few lines need commenting, I also comment the line above and put a
blank line above that and a blank line below, and call it a block:

Code: Select all

[...code...]

; This block resizes the window to match the PanelGadget height.
w=WindowWidth(0)+pgw
h=WindowHeight(0)

[...code...]

And lastly, if a block of code is very long, I comment like the above one
but add dashes to highlight the block to make it easier to see its start
and end points (although this example is not long, but you get the idea):

Code: Select all

[...code...]

; --------------------------------------------------------------
; This block resizes the window to match the PanelGadget height.
w=WindowWidth(0)+pgw
h=WindowHeight(0)
; --------------------------------------------------------------

[...code...]

And I actually have a new one now: If I have a massive block of code
that I re-use in all apps and it's 100% bug-free, I will now IncludeFile
it to save source size, because I know it'll work fine and I know what
it does, so I don't need the reassurance of seeing it in the main source.

Having said all that, you may see code in these forums by me that don't
conform to all that I've said above -- that's because I change my style
for public code, for whatever reason at the time. But for my own code,
that's how I do it.

[Shannara]

I just use the comment character .....

Code: Select all

; This is a comment

[blueznl]

this is my (bad ) style...

Code: Select all

procedure.l abc(x.l,y.l,z.l)          ; this comment helps when folding, may list some parameters
  protected a.l, b.l
  global c.l
  ;
  ; *** describing again what the procedure does, but no desc. of parameters
  ;
  ; in:  x.l       - first parameter and so on, describe...
  ;      y.l = 1   - ah, a one
  ;          = 2   - oh! a two!
  ;      z.l       - no clue
  ; retval   = 0   - error
  ;          = 1   - no error
  ;
  ; here comes my code!
  ;
  ; *** prepare <-- using some stars to mark more important sections
  ;
  ; comments alore comments alore
  ;
  bla bla bla bla
  ;
  ;
  ; *** ah, another important part
  ;
  a = 1
  while a < 100
    ;
    ; keep on doing this
    ;
    a = a+1
    if a > 50          ; sometimes quick comments go here
      a = a+1          ; such as saying: speed up above 50
    else               ; do nothng, huh?
    endif
    ;
  wend
  ;
  procedurereturn 1
  ;
endprocedure

[Guimauve]

My File Header

Code: Select all

; <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
; Project name : The name of the project
; File : The file name
; File Version : 0.0.0
; Programmation : To verify
; Programmed by : 
; Nickname : 
; E-Mail : 
; Date : 06-03-2006
; Last Update : 06-03-2006
; Coded for PureBasic V4.00
; <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

With jaPBe, in solid RED color, when the code is bugged and I need to stop for a long period.

Code: Select all

;/ <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
;/ <<<< LE DÉBOGGAGE C'EST TERMINÉ ICI <<<<
;/ Programmeur : Guimauve 
;/ Date : 06-03-2006 
;/ <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

The End Of File

Code: Select all

; <<<<<<<<<<<<<<<<<<<<<
; <<<< END OF FILE <<<<
; <<<<<<<<<<<<<<<<<<<<<

And my main source code template

Code: Select all

; <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
; Project name : The name of the project
; File : The file name
; File Version : 0.0.0
; Programmation : To verify
; Programmed by : 
; Nickname : 
; E-Mail : 
; Date : 06-03-2006
; Last Update : 06-03-2006
; Coded for PureBasic V4.00
; <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

IncludeFile "" 
IncludeFile "" 
IncludeFile "" 

; <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
; <<<<< The StartCheckup routine <<<<<

StartCheckup()

; <<<<<<<<<<<<<<<<<<<<<<<<<<<<<
; <<<<< Open Main windows <<<<<

ProgramNameWindow()

; <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
; <<<<< The events manager <<<<<

ProgramNameEventManager()

; <<<<<<<<<<<<<<<<<<<<<
; <<<< END OF FILE <<<<
; <<<<<<<<<<<<<<<<<<<<<

Regards
Guimauve