Comments
Let me first give you my old impression of commenting. Lots and lots of
good comments. However this is NOT correct. 'Pardon?' I hear you say.
There are several reasons why this is true. Why do you need comments? Why do 'old-school' programmers say 'I don't need comments. It is easier to read the code not the comments'?
Comments are to supplement the code. It should NOT be used as crutches to explain bad code. In the bad old days, when bad old assemblers and bad old languages (such as the old FORTRAN) were around you could only make identifiers, labels, and routines have a six to eight byte name. This meant that naming could not explain what each section was meant to do. (This, in fact, is a poor excuse)
In high level languages the only comments you need are to give extra 'problem domain' information to the user. As I said in naming conventions, the names in the code, should give enough useful information to the reader to be able to understand it. Any complex, or tricky techniques should be replaced with easier, or broken down sections. Ease of reading is an important feature of code. It is not enough for the compiler or assembler to be able to read it - humans must too.
In assembler, things are slightly different because of the resolution of the code - it is a lot lower level, and therefore a lot further from problem domain. Therefore, comments need put each few lines of code into problem domain.
As an example, look at the following code...
1.BAD COMMENTING WITH NO NAMING ; clear a block of memory of 240 bytes, at the position input in a0. c: move.b #0,d0 ; move zero to the register d0 move.w #60,d1 ; zero 240 bytes xx: move.b d0,(a0)+ ; move d0 to the location at a0, and increment a0 dbra.w d1,xx ; loop rts 2.GOOD COMMENTING WITH NO NAMING ; default the employee structure ; IN: a0 = start of structure c: move.b #0,d0 ; copy the default value to d0 move.w #60,d1 ; the number of bytes in the structure xx: move.b d0,(a0)+ ; default one byte at a time dbra.w d1,xx rts ; end routine 'c' 3.GOOD COMMENTING WITH GOOD NAMING ; IN: a0 = start of structure employee_struct_ptr reg a0 es_default_counter reg d0 es_default_load_value reg d1 default_employee_structure: move.b #EMPLOYEE_DEFAULT_VALUE,`es_default_load_value move.w #EMPLOYEE_STRUCT_SIZE,`es_default_counter defaulting_loop: move.b `es_default_load_value,(a0)+ dbra.w `es_default_counter,defaulting_loop rts ; end of 'default_employee_structure'
In the first example, the comments are of no use (except perhaps to a novice coder, who could not read the assembler mnemonics). They add nothing to the code. Not only that, but they would tend to get out of sync as the code is modified.
The second example is a little better. However, again, the comments will get out of sync, and it is still not the best option.
Now the third example has hardly any comments. The various sections are all self explaining. The two pieces of immediate data in capitals (EMPLOYEE_....) are defined elsewhere, with the variable declaration using an EQUate statement.
Layout
There is a certain personal pride given to code with a good layout. It takes little effort to layout code well, and the result is much more readable. This section examines the subject.
LABEL FIELD INSTRUCTION OPERANDS COMMENT label: move.l d0,d1 ; move something
Compare this with example 3. Above is the classic assembler layout. What are it's problems? For a start. it assumes only short fields. Higher level languages have got rid of their position content in respect to the artificial text file 'line'. In assembler we still are limited by it.
Use the tab key to give you easy access to different columns. In Eddie, as well as in many other editors, you can set particular column settings. Four is quite a good setting, but experiment. The problem with locating with spaces is the slow speed.
Labels. Don't be afraid of big labels. However, DO NOT put a displaced instruction after it UNLESS you have plenty of space to format ALL your instructions on the same column.
Generally, all instructions should start be on the same column. The same
is true for operands. If you cannot maintain this over a whole file - then
the minimum is a logical block of statements. The idea is to give a human
reader some visual connection.
However, do not put a lot of space between the instruction and the operands,
the two should still be close enough to be appear linked.
End of line comments in a block should also be aligned - although one of the problems with end of line comments is the fact it takes so much effort aligning them, and so little work to misalign them!!
This looks messy:
a_long_label move.w d0,d1 move.l a0,a1 ; copy the pointer across move.l #0,d3 ; the first offset rts
This is better:
a_long_label: move.w d0,d1 move.l a0,a1 ; copy the pointer across move.l #0,d3 ; the first offset rts
Back to Assembler Coding Styles