General coding advice for non-programmers

Might also look into some of the sophisticated “no code” development platforms, like Bubble.

You can drag and drop a lot together, and it also rewards deeper tech implementation if you need or want it. Wish I’d had it, um, 40 years ago when I built Trans Fiction Systems in the FORTH programming language, which I used for Star Trek, The Promethean Prophecy and other projects.

(Okay okay, let an old guy humblebrag a little!)

But seriously, Bubble is cool. Built this with it, launching formally in the next couple of weeks:
InventionArtsAI

Ron

2 Likes

It’s not like you don’t deserve it. I remember enjoying The Promethean Prophecy a lot on a friend’s C64 back in the day after the bottomless pit of frustration that The Kobayashi Alternative had been not long before. To me that was the first game that both captured the classic Star Trek tone and was reasonably well designed.

2 Likes

I have been a professional programmer at various points in my life (including my current startup)

There are two big problems most programmers face:

  • solving the problem in front of them
  • working out later what on earth you were doing when you wrote that code

There’s a lot of good advice about the former and not much about the latter.

@Draconis raises a great point about readability, but I would go further.

The key to solving any problem is learning the context. But, once you move on, the context starts to get fuzzier and fuzzier until you lose it completely. Then, absent that context, many contemporaneous notes become unreadable.

Make the context as explicit as possible.

Comments are often brought up but I’ve read far too many comments that were absent any relevant context and therefore incomprehensible when read later.

Let’s take an all too common example:

// set the initial value of “ms” to 1
ms = 2

Setting aside that the comment is a long winded repetition of the code and adds nothing but maintaince burden, what was so special about the value 1? Obviously at some point it got changed to 2. Why? Was that in error? What does any of this mean? It’s very frustrating when you know you that past-you wrote this.

I’m simplifying the example to absurdity in order to get over a point.

In my work I typically try to use functional languages and write functions so small their own name is documentation enough to convey a context.

If I am going to the trouble of leaving a comment I try (and often fail) to communicate the context and intent of what is going on. Here’s the same example again:

// the allocation strategy can be 1 or 2
// depending upon whether we have high or
// low memory. For low memory configs
// it should be 1
mem_alloc_strat = 2

A stupid off the cuff example but the idea is that in the future there is a clue as to the reasoning behind whether this value is 1 or 2 and why it matters. Are we crashing with memory errors? Perhaps try going back to 1 and see if solves the problem.

If we go back to the earlier example. At the time we wrote it, it was obvious that ms was referring to the memory strategy and that 1 was the low-memory strategy and 2 was the high-memory strategy. It was so obvious that we clearly didn’t need to write it down at the time. And so it goes.

This stuff is hard and doesn’t seem to get much easier. The state of the art does not seem to have advanced much since I started writing code in the ‘80s.

Be careful out there folks and come home safe.

8 Likes

I like framing the contents of comments as context for the future reader, most importantly your future self. A similar sentiment is often phrased “comments should explain why rather than what the code is doing” or similar, but as with any prose it’s useful to write for a specific audience and, when appropriate, from a subjective point of view.

Even the line between a comment that uselessly repeats what the code is doing and a comment that provides useful context is audience-dependent. An arcane invocation of an advanced language feature that you didn’t know before and may never see again until you revisit the code could use more notes-to-self than an expert in the language would want/need.

Arguably the highest form of making context explicit is about experiences and thought process from working on the code, as opposed to what’s happening at the time it runs. Here are some examples I’ve personally written many instances of:

  • It looks like doing X instead of Y would be simpler but when I tried that it didn’t work and I couldn’t figure out why so let’s leave it alone :woman_shrugging:
  • This might be wrong (what about […]?) but I don’t have time to look into it right now, if something breaks maybe try […].
  • This looks very similar to the logic in [other place] but there are enough subtle differences that unifying them makes everything more complicated. Trust me, I tried three times already.
  • A cleaner way to do this would be […], but last time I tried that it made [use case/test scenario] slower [numbers if available] and I don’t consider that acceptable.
  • This looks super inefficient because it does n^3 work for n MacGuffins, but right now n = 6 so let’s keep it simple until we have more (if ever).

Some of these things can also be in commit messages, but a comment in the right place jumps in your face when you touch the code again while the history is only consulted on demand. Also, an old commit message won’t get updated when you discover something new (i.e., even if you find one relevant commit there might be a newer one you missed), while an inline comment can be changed or removed. It’s very easy to forget this, code and comments “drift apart” more often than not, but even then you can have the option to notice and fix that drift eventually.

6 Likes

Commit messages can be useful but in my experience they rarely capture a lot of context at a detailed enough level.

What could be huge is if coders narrated their thought process as they go and committed those recordings with the code. So you could mouse over a line and hear what the thinking was as it was written/changed.

3 Likes

That would be cool! I know git has state tracking for who changed what file, sometimes even what line (I think IntelliJ can display the latter in its IDE). But I don’t think that level of documentation commentary exists…yet :thinking:

1 Like

Thanks, @Exemptus! Much appreciated. Glad you enjoyed it. It was a blast to build and write.