• Replies 18 replies
  • Subscribers 24 subscribers
  • Views 6141 views
  • Users 0 members are here
Options
Related

Monkey C Coding Style Guide

dbrobert

I am about to release three Monkey C projects (as barrels), and was thinking that I should probably try to adhere to whatever generally accepted conventions exist. Plus, if any pull-requests are made, it would be good to be able to ensure that any code changes also adhere to accepted coding conventions. However, in an afternoon of perusing Garmin sample code, public repos, code posted in the forums, etc, I have found much variation in almost all aspects of coding convensions.

There has been a lot of activity with 's prettier-extension-monkeyc extension for Visual Studio Code, but I think it would do the Connect IQ / Monkey C community good to put together some sort of style guide, in a collaborative fashion, probably building on some of the rules in Mark's extension. I'm thinking something like the Ruby Style Guide on GitHub. Obviously, like any project in any language, there is no need to adhere to the style (for example, I *detest* this obsession with lines ending at 80 chars) but I suspect it would be useful for any Monkey C programmer to have a style reference.

I am happy to take the lead but would like to gauge the interest of others in helping put an officially, unofficial style guide together.

UPDATE: The first attempt at something concrete is now on GitHub at: https://github.com/douglasr/monkeyc-style-guide

  • in reply to dbrobert

    Until 50% of the people asking questions on the forum have not only not read the Monkey C documentation, nor did a search before they ask something, but a good portion of them haven't even write a line of code in any programming language yet, I wouldn't invest in it too much. The same time you planned to invest in this could be spent on adding other interesting and useful libraries to your repo ;)

  • in reply to flocsy🤠
    flocsy🤠 said:
    Until 50% of the people asking questions on the forum have not only not read the Monkey C documentation, nor did a search before they ask something, but a good portion of them haven't even write a line of code in any programming language yet, I wouldn't invest in it too much.

    You're making a lot of assumptions here. ;)  And you're basing it on one-sided data; we only see the people posting questions on the forums, and not the people who are playing around and/or making apps and not posting anything.

    Besides, if we have a style guide then we have something to point new users to.

    And, if people are answering questions in the forums that could have been answered by reading the existing docs, then we should be pointing new users to the docs instead of answering directly in a post. Or create a community driven "Getting Started with Monkey C" document to point users to.

  • in reply to dbrobert
    dbrobert said:

    Take this code for an approximation of e, written in Ruby:

    estimate_e = ->(trials) { trials.times.map {1.0/trials.times.map {trials.times.map {rand(trials)==0}.count(true)==0}.count(true)}.sum }

    Is it valid and does it compile? For sure. But is it easily readable to the passing eye? Not even close. And yet it's potentially considered clean and uses meaningful names.

    I don't know Ruby, but if this is considered clean it might just be an ugly / write-only language like Perl Grinning

    Guides are suggestions so everyone is free to do what they want, but I think the cardinal rule is (or should be) to program like you would want it to look like if you were coming into someone else's code for the first time.

    I have a Fenix 7X, reasonably fast and new, but not everyone gets a new watch every year so I still have to optimize so calculations can be done in one onUpdate. I also have an old and cracked FR 235, but my watchface runs on it too so at least it's good for testing efficiency.

    Assuming hardware will overcome bad software is what Bill Gates said about windows decades ago. But today Windows 11 might be flashier and marginally less buggy than Windows 3.1, but it doesn't seem like I can work any faster.

  • in reply to dbrobert
    dbrobert said:
    Besides, if we have a style guide then we have something to point new users to.

    Replying with RTFM might sound like a good answer, but I'm with @flocsy here in that there are A LOT of "I'm a lazy noob, solve my problem for me" posts. They get tedious after a while. But, if we did have a fine manual, at least we COULD give that reply.

  • in reply to dbrobert

    The Garmin supplied docs are generally useful, but they assume familiarity with some other languages and programming in general. Maybe a good starting point is to start with a style guide for a language that Monkey C closely resembles. PHP comes to mind.

  • in reply to andyj713

    So maybe we indeed need some pinned post about these things or Monkey C Wiki or something like that. Though that wouldn't help probably when people who can't understand a for loop want to write their own WF :) 

  • It's been a while (okay, over two years), but the officially, unofficial Monkey C style guide is now up on GitHub:

    https://github.com/douglasr/monkeyc-style-guide

    It follows the structure of the Ruby Style Guide, as I originally proposed, but everything has been adapted to Monkey C and Connect IQ. Where a guideline depends on how the language actually behaves (what compiles, what the type checker does, how memory is handled), I checked it against the current SDK docs and the 9.3.0 compiler rather than relying on folklore.

    A few things from this thread made it in:

    •  , your "cardinal rule" is quoted right at the top, because I honestly couldn't have said it better. Your suggestions to guard APIs with has (since the CIQ version alone isn't a guarantee) and to use parentheses for mixed operators are both guidelines now, and the locals/caching advice is in the Memory & Performance section.
    • That section is the "smaller/faster code" section I mentioned. I kept it to things that prevent real problems (circular references, running out of memory in background services and glances) or that cost nothing in readability. Things like inlining functions and pre-computing reciprocals didn't make the cut; I think they're more optimization tips than style, so maybe they get their own doc someday.
    •  , I tried to keep the guide compatible with Prettier's output where it matters, so things like spaces inside dictionary braces and trailing commas in multi-line literals are left to the project to decide, as long as it's consistent. The guide recommends the extension for anyone who wants this done automatically.

    And yes, the recommended line length is 100 and not 80. I said I detest the 80-char obsession and I meant it. ;)

    Nothing here is set in stone. If you disagree with a guideline, think something's missing, or just spot a typo, please open an issue or send a pull request. The whole point is for this to be a community thing and not just my opinion on how code should look.

     , I know you weren't sure this was worth the effort, but here's hoping it gives us something to point new folks to

  • in reply to dbrobert

    FWIW...Thanks!  Us non-programmer programmers need this. I see several ways (and simple reasons why) to improve my code.