Where to place comments?

[Kukulkan]

Hi,

I dont know if this question was already asked (search did not find something) and it sounds like a absolute beginners question but I'm just curious about how others are thinking about this.

Should the procedure comments be located on top of the procedure or inside of the procedure?

Example 1:

Code: Select all

; Insures that given path is returned with the trailing directory #Slash
Procedure.s FixDirSlash(Path.s)
  If Right(Path.s, 1) <> #Slash: Path.s = Path.s + #Slash: EndIf
  ProcedureReturn Path.s
EndProcedure

Example 2:

Code: Select all

Procedure.s FixDirSlash(Path.s)
  ; Insures that given path is returned with the trailing directory #Slash
  If Right(Path.s, 1) <> #Slash: Path.s = Path.s + #Slash: EndIf
  ProcedureReturn Path.s
EndProcedure

The difference is especially visible with folding. The first example shows the comment even if everything is folded. The second one also hides the comments.

So what do you prefer and why?

Best,

Kukulkan

[MachineCode]

Use whatever method you prefer. You've obviously tried both, so which do you like? It's your life.

[Kukulkan]

Hi,

I'm just curious about how others are thinking about this.

I'm working on development guidelines for my developers who are using PureBasic. For now I prefer the comment above the procedure but I'm looking for arguments. I'm curious about how others do it and why. These guidelines have to work for the next years...

Kukulkan

[MachineCode]

I understand you were curious, but I gave you my answer. You can't discount it just because it wasn't what you wanted to hear.

Anyway, if you want a different answer: I'd suggest maybe keeping it inside the procedure, because that way it's all "locked inside" and the comment gets kept if you copy the procedure to another source. But as you said, the comments are hidden when the procedure is folded.

Another suggestion: put the comment at the end of the "Procedure" line. That way it's still "locked in" as part of the procedure, and the comments are also still visible when folded.

Last suggestion: rename the procedure to something totally self-explanatory, so no comment is even needed as to what it does.

Hope that's a better answer.

[Shield]

Usually (in like all the 'big' and not so big languages that support code documentations),
comments are written directly above the construct they are describing.

Sure, you could write comments inside the procedure to "lock them in",
but this doesn't really work if you want to describe a variable for example.

But MachineCode is right, choose whichever you prefer.
I usually tend to write a lot of comments to describe everything:
function, purpose of parameters, return value, ...

[Josh]

To find the best way for my project, I changed my programs a lot of times to find my final style. In my project I'm using a lot of com-objects and to keep the overview, I have to hold the procedures very compact. So a folded block of procedures looks like this:

Code: Select all

 
;-===== I SCRIPT SITE =====================================================
Procedure.i SCE_Site_New                         (*Me  .CSCE)
Procedure.i SCE_Site_QueryInterface              (*This.CSCE_SITE, *iid.IID, ...
Procedure.i SCE_Site_AddRef                      (*This.CSCE_SITE)
Procedure.i SCE_Site_Release                     (*This.CSCE_SITE)
Procedure.i SCE_Site_GetLCID                     (*This.CSCE_SITE, *LCID.Long)
Procedure.i SCE_Site_GetItemInfo                 (*This.CSCE_SITE, VbsName.s, ... Procedure.i SCE_Site_GetDocVersionString         (*This.CSCE_SITE, a)
Procedure.i SCE_Site_OnScriptTerminate           (*This.CSCE_SITE, a, b)
Procedure.i SCE_Site_OnStateChange               (*This.CSCE_SITE, a)
Procedure.i SCE_Site_OnScriptError               (*This.CSCE_SITE, ...
Procedure.i SCE_Site_OnEnterScript               (*This.CSCE_SITE)
Procedure.i SCE_Site_OnLeaveScript               (*This.CSCE_SITE)

All comments are inside the procedures. Inside the 'header' of a block of procedures (;-===) are comments about the block, structures, interfaces, vTables, IID's etc. are needed for the following procedures.

[luis]

I use this format (sample from a lib I'm working on ... )

Code: Select all

ProcedureDLL.i sgl_SetTextureFromImage (hTex, nImage)
; [DESC]
; Set the texture's texel data from the specified PB image.
;
; [INPUT]
; *Tex : A valid SGL texture.
; nImage : A valid PB image (24 or 32 bits).
;
; [RETURN]
; 1 if successful, else 0.
;
; [NOTES]
; The texture must be a new, empty texture just been created with sgl_CreateTexture().
; This command will set filtering, generate mipmaps and set anisotropic level based on the current SGL settings.
; After this command completes the SGL texture is ready to be bind to an OpenGL texture unit with sgl_SelectTexture().
;
; Generation of mipmaps it's a costly operation and so they can be generated only at this moment, when the image is converted to texels
; for the texture. If you want mipmaps for this texture be sure to have #sgl_Cap_Tex_MipMapping enabled before using this command.
; Also if you want the texture to be compressed enable the capability #sgl_Cap_Tex_Compression before using this.
;
; Filtering option can be instead changed at any moment setting the caps and calling sgl_UpdateTextureFiltering().
;
; If you want to replace the texel data with a completely new image destroy the texture with sgl_FreeTexture() and invoke 
; sgl_CreateTexture() again.
;
; If you just want to update the texel data with a compatible (same depth) image but having different size / content use the lighter
; sgl_UpdateTextureFromImage(). 
 
... code ...

EndProcedure

From this I automatically generate a simple documentation for all the public procedures in the library in HTML format.

About the other internal comments, I don't follow any rule.

[skywalk]

Yeah, I also prefer Procedure comments to be subordinate to the Procedure line.
I find it much simpler for code tools that parse them for autogenerated documents.
Also, when navigating the IDE using [Ctrl+k], you jump to the top of the Procedure and still see your comments below.

[c4s]

[...] From this I automatically generate a simple documentation for all the public procedures in the library in HTML format.

[...]I find it much simpler for code tools that parse them for autogenerated documents.

Hm, I'm curious... What tools are you using for this?

[skywalk]

Mine are just homegrown parsing tools.
I've seen more elaborate ones posted that format the output as html.
In general, if you write your code knowing you will parse it later, this influences variable declaration schemes and commenting and datasections, etc. I find it a huge timesaver later, but it does take a bit more time initially to always code in a strict and consistent manner.

[luis]

@c4s

Something I wrote just for this library, because the number of commands was growing so much I felt the need to have a quick way to explore the current command set to make the library grow more or less coherently.
Plus I will probably release it in the forum, so I thought a minimal documentation could help not only myself in time, but everyone else looking at it.

Anyway it's really a simple program, parses the sources, extract the procedures/macros, group them in categories and output the html.
But it's not for general use, no error checking, rigid, etc. Just a tool specific for this lib.

[c4s]

Would be cool if you would release your little javadoc-like tool because I think that PB really needs better documentation support. Note: the help file is great, I mean tools to make it easier to handle our own code...

I just posted a slightly relevant feature request for something that is really helpful when dealing with larger codes and lots of includes: eclipse's javadoc-like hover info

[luis]

Would be cool if you would release your little javadoc-like tool because I think that PB really needs better documentation support. Note: the help file is great, I mean tools to make it easier to handle our own code...

Just to clarify, I was talking about releasing the LIBRARY, not the TOOL. As I said it's crappy, works only with my lib, I talked about it only because you asked it

[c4s]

@luis
Alright, misunderstood that. I still think that PB needs something like that.

[Kukulkan]

Thank you all for your answers. I realize that the question is indeed not that easy as it looks like. The automatic parsing functionality is really a good point to consider. I also realize that it is only a matter of taste to see or not to see the comments if everything is folded.

I will consider some automatic comments parsing in the makefile. Therefore I need to check what we like more for this. I do not see it as more complicated to parse in the one or in the other direction to get the comments. Just have to dig deeper in what we want to do in the future.

Thanks for all the input!

Kukulkan