1. Forum
  2. Usenet
  3. COMP.LANG.MUMPS

  • Routine comment/documentation Standards?

    From Christoffer Engman@21:1/5 to All on Thu Jul 20 11:39:25 2023
    Hi! Im wondering if there`s any "best-practices" when it comes to comment/document your routines etc?

    Im trying to figure out a standard for my-self (and our team) which is the best approach.

    This is an example draft of a routine comment-block. I have tried to include some varieties of input-params since the Routine can do a-lot of different things depending on what the user is trying to solve.

    FRAME(TITLE,WIDTH,CONTENT,DELIMETER,ORDER)
    N (TITLE,WIDTH,CONTENT,DELIMETER,ORDER)
    ;
    ; Render a Window Frame
    ;
    ; @param TITLE {String} The title of the Frame (default: "")
    ; @param WIDTH {Integer} The width of the frame (default: 50)
    ; @param CONTENT {Array|String} The content of the frame
    ; @param DELIMETER {String} The delimeter if CONTENT is a {String} (default: "\n")
    ; @param ORDER {Char} The order of the frame [Upwards = "U", Downwards = "D"] (default: "U")
    ;

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From ed de moel@21:1/5 to All on Thu Jul 20 12:26:53 2023
    When it comes to comments, I always am reminded of a snarky observation by one of my professors in college:
    "If the code and the comments disagree, then both are probably wrong..."

    That aside: I have seen too many comments that just replicate the code. That is a waste of bandwidth.
    Comments should explain WHY you're doing the things the way you chose.
    So: explaining the meaning of parameters, and their ranges of acceptable values is a GOOD thing.
    But, such a comment that just says "A string between 5 and 20 characters" is a waste of effort.

    In the above example: width of the frame; default 50... what's missing is "in which units?" What is "too small"? what is "too big?"

    and so on... I'm sure you get the idea.

    Just my $0.02,
    Ed

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Christoffer Engman@21:1/5 to ed de moel on Thu Jul 20 13:48:42 2023
    On Thursday, 20 July 2023 at 21:26:55 UTC+2, ed de moel wrote:
    When it comes to comments, I always am reminded of a snarky observation by one of my professors in college:
    "If the code and the comments disagree, then both are probably wrong..."

    That aside: I have seen too many comments that just replicate the code. That is a waste of bandwidth.
    Comments should explain WHY you're doing the things the way you chose.
    So: explaining the meaning of parameters, and their ranges of acceptable values is a GOOD thing.
    But, such a comment that just says "A string between 5 and 20 characters" is a waste of effort.

    In the above example: width of the frame; default 50... what's missing is "in which units?" What is "too small"? what is "too big?"

    and so on... I'm sure you get the idea.

    Just my $0.02,
    Ed

    Yeah, you got a point there. The M-Unit tests actually explains more about what the routine does than the actual routine itself.
    The example I posted above is a pure example of which ways the routine could be used. At the moment I pretty much write an "documentation essay" of some routines that I KNOW I will forget how it even works after a year - since Mumps-code is really "
    cryptic" sometimes and really hard to understand what it does from the get-go.

    But some M-Unit Tests is a good idea for "documentation-purposes" and also to maintain the functionality of the routines, so nothing breaks in the future.

    I also strive to build more "Generic" Util routines that can be re-used in other places since it goes against my philosophy that a routine/function/whatever is only being used once and never again.

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From David Wicksell@21:1/5 to All on Thu Jul 20 16:27:17 2023
    Hello Christoffer,

    I used an approach similar to yours, inspired by JSDoc, in a routine I wrote, that might give you some ideas.
    I'm sure there is plenty of room for improvement, but I'll post the link if you want to take a look and maybe it
    will help. https://github.com/dlwicksell/nodem/blob/master/src/v4wNode.m

    There is certainly no standard in the M community, and best practices will vary. Good luck!

    David Wicksell
    Fourth Watch Software LC

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Christoffer Engman@21:1/5 to David Wicksell on Thu Jul 20 17:36:24 2023
    On Friday, 21 July 2023 at 01:27:19 UTC+2, David Wicksell wrote:
    Hello Christoffer,

    I used an approach similar to yours, inspired by JSDoc, in a routine I wrote, that might give you some ideas.
    I'm sure there is plenty of room for improvement, but I'll post the link if you want to take a look and maybe it
    will help. https://github.com/dlwicksell/nodem/blob/master/src/v4wNode.m

    There is certainly no standard in the M community, and best practices will vary. Good luck!

    David Wicksell
    Fourth Watch Software LC

    Thanks! Now I have a little more to take inspiration from. Thanks again! :)

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From K.S. Bhaskar@21:1/5 to Christoffer Engman on Thu Jul 20 18:22:57 2023
    On Thursday, July 20, 2023 at 8:36:26 PM UTC-4, Christoffer Engman wrote:
    On Friday, 21 July 2023 at 01:27:19 UTC+2, David Wicksell wrote:
    Hello Christoffer,

    I used an approach similar to yours, inspired by JSDoc, in a routine I wrote, that might give you some ideas.
    I'm sure there is plenty of room for improvement, but I'll post the link if you want to take a look and maybe it
    will help. https://github.com/dlwicksell/nodem/blob/master/src/v4wNode.m

    There is certainly no standard in the M community, and best practices will vary. Good luck!

    David Wicksell
    Fourth Watch Software LC
    Thanks! Now I have a little more to take inspiration from. Thanks again! :)

    Software maintainers really need to read the code to understand it, not read the comments. That said, comments about what the programmer intended to achieve are beneficial. For what it's worth, https://gitlab.com/YottaDB/Util/YDBAIM/-/blob/master/_YDBAIM.
    m is some code that I wrote recently.

    Regards
    – Bhaskar

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)