Thursday, August 16, 2018

You're doing it wrong: Coding Styles

There has been lots and lots written about coding styles, and I'm writing still more. My basic premise is the same as most of the other articles - everyone else is wrong, so listen to me.

I see the same basic issues pop up over and over again in coding guidelines. The most egregious, or at least the ones that come to mind as I write this, follow:

  • Detailed Guidelines that cover every conceivable syntax case: Here's the first rule. If your coding guidelines take up more than a single page of normally written text - including properly spaced examples - you've got too many rules. Remember that the purpose of software development is to create code, and the purpose of having coding guidelines is to reduce bugs. If your guideline can't reasonably be defended to reduce common bugs, it isn't needed. This is subjective, but this very basic guideline can trim the size of many lists. If you have too many, people won't even remember them, let alone use them.
  • Getting picky over the little things: It's very common to enforce things like whitespace. This tends to be pedantic after a point. In truth, I approve of little things like aligning lists of initializers or cases. (Some people are ridiculously against this, their defense is they don't want to read code in a code review. Use 'ignore whitespace' then. Aligning the code leads to a faster code review because you can just scan the list, instead of searching each line for the important parts. I'll complain about code reviews again someday.) Ultimately, the purpose of software development is to create code, and the purpose of having coding guidelines is to reduce bugs. It's rare that tabs versus spaces break the code.
  • Created by a secret cabal: it's pretty common that coding guidelines are developed by the senior developers and everyone gets to follow them. But unless you're a mega-corp with a company-wide policy and you can't change the rules or your job, the guidelines should be developed by the entire team - even that kid who just finished college and it's his first day and he hasn't even done orientation or dealt with IT yet. There are two very important reasons - it provides a feeling of contribution, and you all have to deal with them - so you might as well agree on them. Be diplomatic but firm about unnecessary rules - but if someone is very persistent and nobody else really cares - maybe consider adopting the rule, even if it is tabs instead of spaces. In truth, the purpose of software development is to create code, and the purpose of having coding guidelines is to reduce bugs. If people don't like the rules, they won't follow them or enforce them, and you've just wasted everyone's time.
  • Not well communicated: I think just about every rant in every field can include this bullet point. You can't just post a note on a semi-private IM chat channel and say you've communicated the guidelines to the group. Communication means making sure EVERYONE has had their say. There are two important parts there - "EVERYONE", and "making sure". Push notifications might cover everyone (might), but if you didn't make sure, you didn't communicate. You broadcast. There's a difference. In the end, the purpose of software development is to create code, and the purpose of having coding guidelines is to reduce bugs. If people don't even know about the guidelines, it's just wasted time (not to mention that means they didn't get their input as in the previous point).
  • Based on the latest trends: also known as "hype-driven development", trends should never be enforced. Most of the time they don't last, and the rest of the time only one or two of your developers know what they are and what they mean anyway. This means that coding the latest cool trick or using some amazing style that you found on a web page will only serve to confuse everyone else. Do note, the purpose of software development is to create code, and the purpose of having coding guidelines is to reduce bugs. If people don't even understand the intent of the whizz-bang feature, they can't effectively use it.
So what is important, then? Coding guidelines should aim to make the code readable. Coding guidelines should include comments - hell yes they should. Comments describe what the code is supposed to do and why it's doing it the way that it is (comments shouldn't describe what the code is doing unless it's really unclear). Coding guidelines should discourage 'tricks' that make the code hard to read (even if it works and is neato-keen) and encourage styles that let the compiler help find bugs. But most importantly, coding guidelines should exist to help the programmer get their job done. 

A secondary goal is to help the code reviewer get the code reviewed, because of course you are using code reviewers who are enforcing the guidelines, right? The code reviewer has their own code to get written, and needs to get through the review as quickly as possible. Basic syntax rules based on common errors make it easy to check if a code should be rejected without having to analyze whether it's actually faulty, which is a huge time saver. At the same time, reviewers should be generous when considering non-bug-causing issues, like whitespace alignment. A programmer who is running through his code fixing whitespace and unaligning lists and alphabetizing includes is not writing new code or testing existing code, which one would expect, is what we'd prefer they were doing. At least if I was paying them, that's what I'd prefer. In addition, after doing all those meaningless cleanups, they then need to repeat all the testing they previously did. Whitespace cleanup costs real money, and software developers are generally not cheap. Ask yourself if changing that tab to a space is really worth $500 or more (time to checkout, fix, build, re-test, commit, restart the code review, reviewers to come check it again...), or if you can just get it next time.

Monday, May 14, 2018

First run of Dragon's Lair Prototype Boards

In order to advance on the hardware side of this, I learned KiCAD and laid out two PCBs. One is the intended final board, and one is a prototyping board that accepts the same ZIF socket for the flash chips as my EPROM programmer does.

I got the PCBs back from OSH Park, and there are a few screwups...

I haven't checked them electrically yet, but there are two main issues - one is OSH's and one is mine.

The OSH one is those connector tabs you see all around the board. I wouldn't generally care, but they put one on the end of the cartridge connector. This has two side effects. First, I need to file it off to make it fit into the port (okay, whatever).

Secondly, and more importantly, whatever method they use to break apart the boards physically damaged the connector:

It's a little hard to see in this photo, but the board is coming apart at the top layer and has actually torn a millimeter or so between the traces. You can most easily see it in the distortion on the one trace.

There's no similar damage on the bottom, so I assume that's the direction they flexed the board to break it apart from the next one.

I'll have to drop them an email to ask how to avoid that on production. It's likely I can use at least one of these boards for prototyping and testing.

The other problem is I apparently didn't measure out the adapter board correctly, because it's completely wrong. It has two parts - the large DIP footprint and the smaller 10-pin header. I managed to make the holes too small for the DIP part and use the wrong pitch and misaligned the 10-pin header. GO ME!

I have three of the adapters, just in case, so I think I can fake it by bending the very long pins on the 10-pin header, and I'll just have to force it or grind the pins to fit the DIP (or use my I-do-this-every-time trick of soldering smaller leads onto the pins... sigh. Someday I'll remember that sockets use thicker pins...)

Anyway, in the middle of moving, but I need to try and test this out as quick as possible, because the next challenge I'm facing is that the 1gigabit chips are obsolete and getting hard to find. OH BOY.

Edit: As Captain C used to tell me: 'Never underestimate the power of force!' I literally used a hammer. ;)

Wednesday, March 7, 2018

It's not Lego!

While pondering why it is that the state of software development has reached the point that it's at (which very patient long term readers will remember is my usual gripe. Blogger says there are 3 of you! ;) )... where was I?

Right, so anyway, projects seem to be planned very strangely. There are cycles and cycles of proposals, and pre-pre-design documents (though rarely an ACTUAL design document). We have processes designed to break tasks down into a bullet point's worth of work, and we consider that planning. We have code management systems that make actually looking at the code the hardest thing to actually do (I'm looking at YOU, Gitlab...)

And while going through all this in my head and trying to reconcile with the task I'm trying to complete myself, I grumbled to myself "code is hard". And that was the revelation.

Oh, I've always known that it's hard to write good code. Anyone who tells you otherwise is either a liar or a genius, and the odds are heavily stacked in one direction. But I've never had that thought in this context. And that's when it all fell together for me.

Coding is increasingly treated as one of the least important parts of the software development process, maybe second only to testing (which will be a rant one day). And yet coding (and testing) are the only parts of the process that actually matter. They are the only parts that actually produce product at the end of the day.

And so as I was thinking that coding is just brushed off as the least important part of the planning process. It seemed like the assumption was that it was going to be easy to get it right, and testing would be covered by the process. So don't stress that part. And then I realized, there IS a style of development for which this is so, and it's increasingly proposed as the right way to do things.

And that style is: don't do it.

Think about it. You've been on the project that said "can't we just buy a package that does that?" How about "is there a library we can use?"

And so I'm of two minds here. The first one is that, well, yes, re-use is a good thing. Yes, many many many tasks have already been developed in one form or another. And no, I don't desperately want to write a USB stack from scratch. So we can just go out, and take all these pre-written libraries, and write a few lines of glue code, and not only is it likely to work, but it's been mostly pre-tested.(Or, so we blindly assume...) Hell, at this point we're not even the performance bottleneck, so let's just write it in script!

The other mind is the reality that I live in anyway where the exact things we want to do don't exist, and so we're building them. But we still use that building-block mentality. We don't consider that maybe nobody actually knows how to do that, and so it's going to take time to get it right. There is still a world where the hard code isn't written yet.

We've reached a point where many people assume that if something doesn't exist, it's because it's too hard to be possible. Don't you believe it. It only means that someone hasn't done it yet, and nothing more. Get out there. Write the hard code. Get it wrong! Then figure out WHY it was wrong and get it right. Odds are, by that point you'll have created something better than anyone before you did.

Oh, and if you're a project planner, realize that hard tasks take time. ;)

Tuesday, November 7, 2017

Investigation continues...

I went through and verified the pinout of the cart, and burned a new AVR and dropped it on the board to test, but it's still working just as flakey. A couple of things were interesting.. one is that when it partially works, it seems to get most of the bytes right (because the program selection is mostly correct). That seems to suggest either I am lucky or the address code is working. (I suspect the latter - if I was lucky I wouldn't be having an issue).

Putting the logic analyzer on it was all over the place, to the point where I couldn't make sense of what I was seeing. But I also determined that my console's power switch is wearing out... so I need to make a repair there to continue anyway.

One thing that has crossed my mind is that with the new compiler, the code may be running too fast. I check the MDIR and MODE pins immediately after detecting GSEL -- maybe that's too fast? When I get the logic analyzer properly on the bus I will recheck that theory.

This shouldn't even be an issue, but I am leaning back towards the ROM-based cart.... I just want this part to work. ;) But in the meantime, I relaid-out the cart to use the ATTINY861 instead - it's a 20 pin part instead of 14. So it doesn't look as much like a GROM, but it has enough pins to bring out the ISP header. I also positioned it so, in theory, the ZIF socket will fit on the board when in the console. I haven't ordered this board or the new parts yet though...

I probably should test programming one of the 128MB flash chips as well -- if my new programmer can pull that off, maybe I should stop wasting my time with the GROM emulation. (But darn it, this part was supposed to "just work". ;) )

Saturday, November 4, 2017

Didn't Work First Try

Never should expect that it will, but I'm a bit disappointed and frustrated at this point.

I had two things to do today - the first was to port my GROM simulation code to the ATTINY84 that I selected for GROM boot. I thought it would be nice to have that to startup, and I could use the EEPROM for high score saving.

That port went reasonably well, and for the most part it did what I expected. Then I shut off the reset pin and discovered that I don't seem to be able to get high voltage serial programming, needed to reprogram it without a reset pin, to work. I spent several hours on this, including research and rewiring it repeatedly. I seem to recall having this issue before and eventually deciding keeping a reset pin was a good idea, but I need every I/O an ATTINY84 has. I think I may nudge up to the next physical size.

Then I went to build the cartridge prototype, and pretty much everything on that PCB was problematic.

First I detected that I didn't actually buy all the ICs I needed to assemble it. I was able to raid the parts bin but it was frustrating. Then, of course, the ATTINY footprint was too close to the IDE port to allow a ZIF socket (I always forget how big they are), and I forgot that the pins need to be larger.

I soldered leads to the ZIF socket to get it on the board, and forgot you need to do that when it's OPEN, not closed, because otherwise the sockets don't always open up for you. ;)

Finally, I got it all together and plugged it into the TI. It didn't come up reliably, it's very flakey, but at this point I think I'm done for the day. When it did come up, the data was correct. I got as far as seeing the menu entries and even getting Easy Bug to start booting, so the basics are working. Either there's some timing issue or I configured one of the I/Os wrong, or (worst case) the IDE circuitry is interfering.

Because I was too dumb to test it before I put the IDE circuitry on.

So I think the next step is to take Jim up on his layout offer while choosing a new chip for this approach, and we'll see which layout works first. ;)

Also did a few surveys to see what people thought about dither patterns. My first favorite was shot down pretty hard, but in the second pass there are two contenders neck in neck, one of which IS my favorite. Sadly there are only about a dozen votes, which speaks lovely for the potential market of this thing. Oh well. ;)

So it looks like we'll be using an ordered dither, but in order to get around the terribly washed-out effect I was getting, I introduced back in a tiny bit of error distribution. It makes a difference in the color yet preserves the more regular patterns of the ordered dither, and I'm pleased that people like it. It's really down to whether I'll use the 2x2 or the 4x4 pattern at this point. (When I re-encoded, I'll probably just do the top four so I can change it out again at the last minute without fearing that the frame numbers might change...)

You can see the current challenge video here (if you can get past Youtube's scaling...):