Saturday, December 17, 2016

Ten programming hints. For Christmas (part2/3)

What I'm
about to say, is probably NOT what you learned at school. School often tells to
throw a whole book of comments in your code. So somebody else can pick it up
more easily… If he reads that whole book, that is. Hence, there is often more
comment than actual code. And who's reading that? Exactly. Nobody. You're not
reading it, because you already know what that code does. That other guy isn't
reading it either, because nobody likes to read a whole book. Especially not if
its code-comment. If code cannot be grasped within a short amount of time, programmers tend to call it junk and start to rewrite it. With their own junk.

I'm not
saying comments are stupid. I'm saying just don't overdo them. In the basis,
your variable and function names should be self-explanatory enough. Captain
obvious, but still we tend to complicate those functions by letting them do
additional stuff the reader wouldn't know. If we call:

BarberCutMyHair(
Prince_Of_Bel_Air_Style )

We don't
expect it to paint my toe nails as well, get outa here. Keep it simple. A
"Cosine" function performs the cosine. Nothing more, nothing less.
And if you're getting a big load of functions, split them into groups or modules. And eventually make helper-functions on top that do multiple things (and clearly explain that - here you
have your comment). Using the right names is worth far more than some comments
to explain afterwards.

Your
teacher may not be happy with the second version, but we are smart enough to
understand what's going on right? Get rid of useless comments, and keep them
for grouping your function into sections, or for REAL important notes. So... if
you see comments, you are actually TRIGGERED to read them, because you know something
useful is in there.

Speaking
of Readable code. I hate those auto-completion editors that force the tabs for
you (some do a good job though). What I always do, is adding one or few tabs on
the left side. You know why? So I can forward TEST / TODO / ERROR comments and
code to the far left. If I scroll down quickly though a document, I can
immediately pick out stuff like this, without even reading the code. Thanks to their
ugliness, comment lines like these stand out, and don't get lost between the others:

function addTwoNumbers( const A, B : integer ) : integer;

begin

result
:= A + B;

// TEST. Lets multiply instead baby

result := A * B;

end;

This is the type of screen I'm looking at 99% of my life, so I'd better
make it tidy.

Starting
a new project, excited. Code rambles out of your fingers like a MG42
machine-gun. Man, you’re just too cool. Four months later, it’s done, and you
move on to another project. Four years later, some annoying bitch in the office
emails that the Export-to-Excel-button doesn’t work anymore. It says “Access
Violation F00236A”, or something. Lame.

If your
program were to be 400 lines only, I bet you’ll patch it up in no time, doc. If
it’s a 40.000 line program doing a lot more, thing may get a bit more tricky.
Maybe there are 10 screens with “Export” buttons, but of course she forgot to
mention which one, or what options she checked. And if there are 4 files, 6
different classes, and a few thousand lines behind those buttons, hidden deep
inside the code, I’m pretty sure you’re not that excited to debug it, four
years after.

Well,
things like that happen regardless. And all the lessons you learn here about
avoiding stupid comments, using “Try Catch” and error messages, Modular design,
or having Readable code in general will be helpful. Hence, you may even want to
consider your work tools at forehand when this scenario is to be expected. C++
(or Delphi / Java / VB / … any written language) are relative hard to analyse
and fix, in general. PLC ladder diagrams or other tools that let you code in a
more visual, “block-to-block”, way, are usually much easier to figure out.
Eventually even by another person, years after.

It’s one
of the reasons we use IQAN at work for mobile agricultural equipment. I do get
phone-calls –and always on Sundays, when I’m shitting, drunk, or hanging upside
down- with strange problems on eight-year old machines. The track-suspension
doesn’t work, why?! Obviously I don’t remember all the conditions and possible
error situations, so I’ll have to dig in the code. And thanks to the
straight-to-the-point, visual way and live-debugging tools, I only need a few
minutes usually to get familiar with the code again and figure out what’s going
on.

What I’m
trying to say here is, the choice of this tool saved us dozens of hours, money,
and angry clients waiting on a broken machine. As much as I love “normal”
coding, I would never pick C++ or the likes for this type of application.

But, if
you are stuck to a written language, then at least try to keep your code clean
and compact. Less lines = less reading = shorter learning curve = quicker
results. Nice and all, but it’s not that Bill Gates can order his programmers
to downsize the Windows OS to 600 lines, or a 64K program. No, of course not.
But still, you could:

·Split
one SuperProgram up into smaller task-specific “Apps”

·Make
reusable modules (see 7) and build these “Apps” on top

·Don’t
bang all your code into one huge file

·Move
the bigger / more complicated code into the background (files, modules, …)

In other
words, if you’re looking for “Export” related code in your program, don’t slap
the reader with other functions, classes, files or global variables that have
nothing to do with it. And if possible, keep the programmer completely out of certain sections. If my graphics look like crap, I'm not digging in actual OpenGL library code either.

On a
more global level, it’s useful to draw boundaries. And be clear about them. Why
did the office lady get that “Access Violation” in all of a sudden? After four
years? Something must have changed apparently. Newer version of Excel? Bloody
Windows10 again? Tried something different than usual? And there you have it:
her computer crashed because she spilled donuts in the CD-ROM drive, so IT gave
her a new station and OpenOffice was installed instead of MS Office. Yep, that
won’t work. Stupid lady. Stupid IT. Or stupid program, for not telling what is
missing? Don't promise rockets if you're making a boat.

When
making a bigger, multifaceted application(set), chances are you’ll get some
common functionality beneath it. For example, let’s say you work a lot with XML
files. Instead of re-writing a Reader/Writer function in every program, it’s
better to make a “XML library” that can be reused in all your programs. A
library could be just some shared file, or a DLL, statically linked library, or
maybe even an API running on some web-service. Depends a bit on the
circumstances.

Anyhow,
as you also learn with OOP (Object Oriented Programming), you’ll be making
reusable code-parts sooner or later. Classes or functions that are used on
multiple places, and inherited by “superClasses”. After a while, you will also
learn that some of those classes can also be useful for other programs. So you
probably share code-files to begin with. When growing even further, you will
get a whole collection of such “common functions”. Could be a XML library, a
math library, sound, graphics, communication… So, you decide to pack them
together in a DLL, API, Framework, or whatever you’d like to call it.

At
least, that’s what you should be doing. However, as logical as it sounds, it can
still be hard to make truly reusable functions, worth being in their own
library. When you try to rip out your “AwesomeStuff class” and put it in a
separate library (project), chances are it won’t work. Because “AwesomeStuff
class” is depending on a lot of other code or variables in your original
program. So you start moving them over as well, even though you feel those
functions don’t really belong in a separate library. Setting up the same stuff
on two places, too specific, too much ties and principles inherited from its
original host program.

That doesn’t
make good modular code. I’ve seen people trying to create their own
“AwesomeStuff DLL” just because they feel it’s a good thing to do. But when
looking into that DLL, it’s not all that awesome. It’s actually pretty much
bound to a very specific application, and for the sake of easy debugging, he or
she would have been better off leaving that code just there –in its original
host program. It’s like stealing somebodies child, putting it in another house,
and then tell its original parents to raise it.

Still,
you have that urgent feeling you should be moving your more common functions to
a library; modular design, you know. Cool, but do it in the right order. When
restarting Engine22, or when making a machine-display Framework at work, I
started building these modules first, instead of making the final program and
ripping out common functions. Or actually, I started on paper, making up what
would be good candidates to become (stand-alone) modules. There are no strict
rules, but at least some guiders you can use:

·Group
and separate logically:

oAs
mentioned in Point #5, the name of a module should be self-explanatory as well.

o“Sound”
does Sound. Not Physics or Aerobics.

oThen
again check if it’s worth making a module. If there is just a few functions,
giving its own module might be a bit overdone. Don’t end up with fifty DLL’s
for every fart.

oDraw
on paper. Robust names, not too much dependencies? Can you explain this to a
non-programmer? Bingo.

·Try
to disconnect your head from one specific Target application (“Tower22”):

oUse
functions that can be used in multiple scenario’s

oFor
my Machine Display Framework, I thought about harvesters, but also about
cranes, dumptrucks, ships, …

oBut
do not implement scenario-specific features. Provide help-functions they can
use instead. Keep the actual Rocket-booster logic for “Spaceshuttle.exe”. Or
make layer in between for that.

oSo
keep it generic, yet clear.

oA
function is what it is. Nothing more, nothing less. No hidden bonus-goodies.

oDevelop
and compile your library as much stand-alone as possible

oUse
(small) test-programs to, well, test it

·Place
yourself in another developer, using your library

oThe
main purpose is to SIMPLIFY; do hard work via a few easy functions

oAgain,
good naming is key

oThe
less your library exports, the easier to learn

o10
functions are easier to master than 1000 functions

oBut
again, be careful not to make your functions to much “multi-purpose”. A
“readXMLfile” should just read the file. Not actually trying to parse it and do
stuff. Split up when needed.

In a nutshell,
try to separate common & application-specific parts. A library like OpenGL
offers a big bunch of generic 3D-drawing functions, but doesn’t do any specific
rendering-technique for you. It does not calculate collisions, draw shadows or
make awesome reflections. It just gives you the tools to get there easier.

It’s not
uncommon to make a more specific module on top of more abstract modules though.
The Engine22 “Graphics” module is basically a wrapper that brings all the
OpenGL magic together. So that I don’t have to worry about it anywhere else in
the code. Not a single OpenGL command is written outside that module.