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
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
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 WicksellThanks! Now I have a little more to take inspiration from. Thanks again! :)
Fourth Watch Software LC
Sysop: | Keyop |
---|---|
Location: | Huddersfield, West Yorkshire, UK |
Users: | 300 |
Nodes: | 16 (2 / 14) |
Uptime: | 106:07:00 |
Calls: | 6,700 |
Files: | 12,232 |
Messages: | 5,350,363 |