Announcement

Collapse
No announcement yet.

Where to COMMENT

Collapse
X
  • Filter
  • Time
  • Show
Clear All
new posts

  • Where to COMMENT

    While I'm wondering today ... I always wondered why folks put comments between procedures instead of in the procedure itself.

    Code:
    Sub Test
       Local x as Long
       x = 5
    End Sub
    
    'comment
    'comment
    
    Sub TestB
       Local x as Long
       x = 10
    End Sub
    I frequently move functions around in my code, regrouping them for a variety of reasons, such as putting the most recently modified procedure at the bottom to make it easy to get to via the keyboard. Having comments in the dead space between procedures seems awkward, if for no other reason than I have to remember if the comment is for the procedure above or the one below. I'd worry that when moving comments I would miss them or move the wrong comments.

    I've even written a utility that would alphabetize the procedure order, which definitely does not handle the floating comments correctly.

    But, I've seen some of our very best coders use the approach, so perhaps there are reasons for it that escape me? Perhaps other folks very rarely move their procedures around?

  • #2
    'This function does so and so '' I'll put outside. Like (or with) a title. A whole line of dashes (or some symbol character) above that to separate from previous function (or sub).

    Remarks describing a section of code go inside.

    Again, just preference. They are free as far as run time is concerned, and nearly so at compile time. If you're going to read the code later (or is demo for someone else) be generous!
    Dale

    Comment


    • #3
      Personally I like to comment routines IN the routines.

      One anecdotal comment, the code formatter I wrote many years ago (was in the PB downloads) had some issues with BEFORE routine comments, hence me forcing my own process to include per-routine comments IN the routine itself. My latest formatter iteration no longer has the same issue, but I still prefer IN routine.

      "Comment culture" also goes so far as to where to put per-code-line or per-code-concept (multiple lines of code handling a single concept) comments go...
      • do they go BEFORE the line/concept
      • ON of the line (mostly only applicable to per-code-line)
      • AFTER the line/concept (meh).
      For lines/concepts I like to do it BEFORE the line or concept, unless it's a really short line really short comment, then I'll do it ON the line at then end.
      <b>George W. Bleck</b>
      <img src='http://www.blecktech.com/myemail.gif'>

      Comment


      • #4
        I'm glad the compiler allows us to put comments almost anywhere and in almost any fashion.
        Comments before code tell you what you are going to do wrong.
        Comments in code tell you what you are doing wrong.
        Comments after code tell you what you did wrong.
        Rod
        "To every unsung hero in the universe
        To those who roam the skies and those who roam the earth
        To all good men of reason may they never thirst " - from "Heaven Help the Devil" by G. Lightfoot

        Comment


        • #5
          Originally posted by Gary Beene View Post
          I've even written a utility that would alphabetize the procedure order, which definitely does not handle the floating comments correctly.
          Hahaha ... I started out commenting above the procedure header. Then bakc in the days, just like you, I wrote a code sorting tool in PB/DOS. And I stumbled over the exact same problem. That's when I moved my comments below the Sub/Function line.

          Comment


          • #6
            The one thing that I miss the most moving from Microsoft PDS 7.1 to PowerBasic was that each routine had its own window. If you wanted to move from one routine to another, you had to use a drop down menu to change. All you could see at one time was one Function/Sub. I searched for an editor that would still give me that functionality but didn't find anything. Folding/unfolding isn't the same. Probably have to write something someday.

            The reason that I bring this up is because any comments above/below/inside the function can only be seen while looking at that function. There would be no question that these comments were for the function on the screen.

            If I can't have one screen per function/sub then I prefer above... a holdover from Assembler days.

            Frank
            Last edited by Frank Rogers; 9 Nov 2018, 05:19 PM.

            Comment


            • #7
              I wish I obeyed my own rule of writing comments before I write the sub. it would save me a lot of time.
              [I]I made a coding error once - but fortunately I fixed it before anyone noticed[/I]
              Kerry Farmer

              Comment


              • #8
                I prefer placing all comments inside a procedure. After the first line (SUB(...)/FUNCTION(...) AS .../METHOD(...) etc) a procedure header follows (enclosed into two separator lines "'********...") explaining what the procedure does, what goes in and what goes out.

                Then all local and static variables follow, one line for each variable. I always use the same variable names for the same tasks, e.g. "i" or "n" for intermediate LONG/DWORD values or loop counters. Non-common variables get a describing comment on the same line and at a fixed column, if possible.

                I try to keep consistent spacing and indentation for code and when adding a comment i always comment on the same line at a fixed column. If the available space in this line is not enough, i add another (properly indented) comment line.

                For me this separates code and comments in a way that i can read the code (and the comments) top down without one "disturbing" the other. One of the features i like most in my own IDE, is that i mis-use the TAB key for placing comments in the correct column. This makes it easy to get and maintain the above mentioned format.

                All of this may seem complicated and too much work, but from experience it definitely will pay off a hundred times, if you must revisit sections of code you didn´t work with recently.


                JK

                Comment


                • #9
                  Coming from QB/PDS myself, I was initially in the habit of comments describing the sub/function after the FUNCTION/SUB statement. When I started using editors with code folding, the description block got moved to above the function declaration so it would still show. Comments about specific lines or snippet of code are in-line, of course.
                  Real programmers use a magnetized needle and a steady hand

                  Comment


                  • #10
                    I use comments inside and outside of functions.

                    Code:
                    'Begin: Graphic-Functions
                    '========================
                    
                    Sub GF_A
                    'Method A -> quick result
                    
                       Local x as Long
                       x = 5
                    
                    End Sub
                    
                    Sub GF_B
                    'Method B -> exactly result
                    
                       Local x as Long
                       x = 10
                    
                    End Sub
                    
                    'End: Graphic-Functions
                    '^^^^^^^^^^^^^^^^^^^^^^

                    Comment


                    • #11
                      I am creating comment headers above the function / subs, describing the arguments passed and returned. Example:
                      Code:
                      '-------------------------------------------------------------------------------
                      '   GBS_Open
                      '-------------------------------------------------------------------------------
                      '
                      '   Creates a ddoc document
                      '
                      '   Arguments passed   :  sDocN             Document name
                      '                         iOrie             Orientation
                      '                         iOptn             Options
                      '                         sCopR             Copyright remark
                      '   Arguments returned :  (Function value)  long
                      '                                           positive: GBS Handle
                      '                                           negative: -Error
                      '
                      function GBS_Open(sDocN as string, _
                                        iOrie as integer, _
                                        iOptn as integer, _
                                        sCopR as string) as long
                      
                          local hDdoc   as long
                          local lTemp   as long
                          local lHand   as long
                      
                          hDdoc = dpStartDoc(0,bycopy sDocN,"", %DDOC_INCH, _
                                             %DDOC_PAPER_A4,bycopy iOrie, _
                                             %DDOC_BIN_AUTO,bycopy iOptn)
                          if hDdoc<1 then
                             function=hDdoc
                             exit function
                          end if
                      
                          for lTemp=1 to ubound(gGBSP)
                              if gGBSP(lTemp).dhand=0 then
                                 lHand=lTemp
                                 exit for
                              end if
                          next lTemp
                          if lHand=0 then
                             function=-100
                             exit function
                          end if
                      
                          gGBSP(lHand).dhand=hDdoc
                          gGBSP(lHand).orien=iOrie
                          gGBSP(lHand).copyr=sCopR
                          gGBSP(lHand).docna=sDocN
                      
                          gGBS_LMarg(lHand) = val($GBS_LEFTMARG)
                          if gGBSP(lHand).orien=%DDOC_PORTRAIT then
                             gGBS_RMarg(lHand)=val($GBS_RIGHTMARG_P)
                             gGBS_Centr(lHand)=val($GBS_CENTER_P)
                          else
                             gGBS_RMarg(lHand)=val($GBS_RIGHTMARG_L)
                             gGBS_Centr(lHand)=val($GBS_CENTER_L)
                          end if
                          function=lHand
                      
                      end function
                      
                      
                      '-------------------------------------------------------------------------------
                      '   GBS_Title
                      '-------------------------------------------------------------------------------
                      '
                      '   Passes the title line to GBS
                      '
                      '   Arguments passed   :  GBS handle        handle
                      '                         GBSL structure    title line
                      '   Arguments returned :  (Function value)  long
                      '                                           positive:  # lines remaining
                      '                                           negative: -Error
                      '
                      function GBS_Title(lHand as long,uGBSL() as GBSL) as long
                      
                          local hDdoc   as long
                          local lTemp   as long
                      
                          hDdoc=gGBSP(lHand).dhand
                          if hDdoc=0 then
                             function=-101
                             exit function
                          end if
                          redim preserve gTitl(1 to %GBS_MAXDOCS,1 to ubound(uGBSL)) as GBSL
                          for lTemp=1 to ubound(uGBSL)
                              gTitl(lHand,lTemp).posit = uGBSL(lTemp).posit+gGBS_LMarg(lHand)
                              gTitl(lHand,lTemp).align = uGBSL(lTemp).align
                              gTitl(lHand,lTemp).style = uGBSL(lTemp).style
                              gTitl(lHand,lTemp).fsize = uGBSL(lTemp).fsize
                              gTitl(lHand,lTemp).datac = uGBSL(lTemp).datac
                          next lTemp
                          gGBSP(lHand).titlp = %TRUE
                      end function
                      I have learned this in the 70ies when programming pdp11-systems.
                      „Let the machine do the dirty work.“
                      The Elements of Programming Style, Brian W. Kernighan, P. J. Plauger 1978

                      Comment

                      Working...
                      X