pushbx wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Overview of educational topics ======

This article lists some topics I think any education on program logic work should cover. I collected these notes over several months, though I have thought about many of these for years at this point.


===== Debugging =====

Debugging is a crucial skill for working with software. Whether it be tracing, inserting log or print statements, or "rubberduck debugging" (explaining the logic of the program to someone else or to an object).

For tracing that uses disassembly, a way of showing the corresponding source text is useful. For our programs, we create trace listing (.tls) files to allow the TracList companion application to trace through the source text alongside the disassembly listed by the debugger.


===== Comments =====

As often stated about perl, programming can often end up as a "write-only" exercise. Comments are useful to communicate what is being done, and why. This is not purely for the benefit of other readers: Coming back to some code weeks or even years later, you will have forgotten the context of what you wrote. Better comment in time to remind yourself of what you did, and why, and how.


===== Usage conditions and licenses =====

As a programmer you should be familiar with the way copyright attaches to any creative work by default. Further, you should choose a free, libre, open-source software (FLOSS) license for your work so as to enable others to re-use it. License proliferation is to be avoided. You should know the difference between permissive and copyleft licenses.


===== Source control =====

Keeping a log of what you changed, and when, is invaluable. You do have to decide how granularly to record changes, but you should commit to an SCM more often than you prepare releases.

Something I dislike about how some people use SCMs is to record very large changes, with multiple unrelated parts, or to specify changeset messages that do not match the contents of the changeset.

Ideally, every changeset should build and run fine without additional changes. This is particularly useful in order to enable bisecting to find the cause of a bug. (If multiple repos are involved then ideally at any single point in time, the combination of then-current changesets should run together. This is not always possible.)


===== Work incrementally, test often =====

Related to source control, I recommend you create small changes that build (assemble or compile) and test them often. The changes may even be smaller than what you decide to commit into the SCM. The point is to build frequently and clean up things so that the build works and does something verifiable. This lessens the workload of making the build work after many untested changes that create a castle in the air, and localises the context to remember to make particular parts work.


===== Object orientation =====

This is a classic gripe about the education I received. Everyone talked about object-oriented programming but no one set out to define exactly what it is, beyond vague assertions that "objects map to real world concepts".

What object orientation means is there's a way for the user to define types, also known as classes, which can combine some amount of data and code. An instance of a class is an object. The code that is defined for a class can operate on objects of this class. Classes can be related in a "is-a" or "has-a" way with other classes.


===== Study existing programs instead of studying or creating toy examples =====

I'm not completely opposed to toy examples, they have their place. That place, however, is to test and understand particular features in isolation. I don't think toy examples are as useful to "learn" programming overall.

What I prefer is to study and modify existing software. Of course, the source text being available is a prerequisite to that. This also requires being able to build the software in question from its sources (which is unfortunately not always trivial).


===== Search the web or references often =====

Especially when working in a language that I don't know very well yet, referencing features that I'm unsure about is very important. Depending on the language, a single reference may be most useful, or searching the web for similar questions may prove fruitful.


===== Tests =====

Automating tests is good. I wouldn't go so far as stating it's necessary, but it can be useful. Either way you want to test and verify (new) functionality frequently.


===== Issue trackers =====

Issue trackers allow to document or comment on particular bugs, or topics more generally. They can be easier to search than the source texts. They are easy to reference from elsewhere as a canonical source of truth about a given question.


===== Documentation / manuals =====

Future users, including yourself, will benefit from documentation. This may be less useful for developer tools (eg ident86 and fixmem.pl) but will greatly enhance the user experience for more user-facing parts.


===== Units and unit prefixes =====

You should know what a bit, a byte, and an octet are. Furthermore, the differences between SI kilobyte (kB), IEC kibibyte (KiB), and JEDEC kilobyte (KB) are essential knowledge to avoid confusion. For x86 programming, the terms word, doubleword, and quadword are required as well.

Briefly, for SI the prefixes are powers of 10 (and the k short form for kilo is not capitalised). Therefore 1 kB for SI is 1000 Bytes, 1 MB is 1_000_000 Bytes, and so on. IEC uses kilo-binary or kibi, short Ki, for 1024, a power of 2. JEDEC abuses kilo (short as capital K) to mean 1024, hence 1 KB for 1024 Bytes.

One problem with the JEDEC use is that it becomes inconsistent when calculations involve different units. 1 MB is 1_048_576 Bytes, but 1 MHz is 1_000_000 Hz. How much data does a transfer move that runs at 1 MHz and processes 1 Byte per cycle? Not "1 MB per second"!

The default format of the venerable 90mm diskette (aka "3½ inch" diskette) is not 1.44 of anything, neither MB (SI) nor MiB (IEC). It is actually 1440 KiB, which comes out to 1.47 MB or 1.40 MiB.


{{tag>education}}


~~DISCUSSION~~