Routine comment/documentation Standards?

Skip to first unread message

Christoffer Engman

Jul 20, 2023, 2:39:27 PMJul 20
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.

; 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")

ed de moel

Jul 20, 2023, 3:26:55 PMJul 20
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,

Christoffer Engman

Jul 20, 2023, 4:48:44 PMJul 20
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.

David Wicksell

Jul 20, 2023, 7:27:19 PMJul 20
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.

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

David Wicksell
Fourth Watch Software LC

Christoffer Engman

Jul 20, 2023, 8:36:26 PMJul 20
Thanks! Now I have a little more to take inspiration from. Thanks again! :)

K.S. Bhaskar

Jul 20, 2023, 9:22:58 PMJul 20
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, is some code that I wrote recently.

– Bhaskar
Reply all
Reply to author
0 new messages