Fire Alarm System Homework Help

also,
over the entru window, if you looked, you would see how to place source code.

I second Pers comments re comments
H3: MOV R4, #242 ;put 242 in R4
does not say squat, and where a comment would be useful, there is none.

general re comments

actually you con, in most cases 'comment' in two ways a) a comments and b) meaningful lables

e.g.

typedef enum
{ ALL_LEDS_OFF = 0xFF
...
...
}t_led_bits

and
#define Po LED-PORT

then

mov LED_PORT,#ALL_LEDS_OFF

is self commenting

do not fall for the fallacy that C is self commenting,that is only true with meaningful lables

also,
over the entru window, if you looked, you would see how to place source code.

I second Pers comments re comments
H3: MOV R4, #242 ;put 242 in R4
does not say squat, and where a comment would be useful, there is none.

general re comments

actually you con, in most cases 'comment' in two ways a) a comments and b) meaningful lables

e.g.

typedef enum
{ ALL_LEDS_OFF = 0xFF
...
...
}t_led_bits

and
#define Po LED-PORT

then

mov LED_PORT,#ALL_LEDS_OFF

is self commenting

do not fall for the fallacy that C is self commenting,that is only true with meaningful lables

No language is self-commenting.

The language and symbols may help tell a story of what is done.
But it can't tell why it is done.

HERE: JNB A, HERE ;

Very unlikely that this is what you want.

JNB if Jump If Not Bit.

A is NOT a bit. It's the ACC register.

It will assemble, but do you want to really test the bit that has the address of ACC?

No language is self-commenting.

OK.Per {is "some statements using meaningful names are self explanatory to the extent that a comment would be superfluous"

I am a great believer in commenting intentions, but have seen too many comments of actions like
mov LED_PORT,#ALL_LEDS_OFF // turn LEDs off
that makes the essential comments disappear in the haze.

mov P0,#255 // shuld, of course be commented
but
mov LED_PORT,#ALL_LEDS_OF // is self-explanatory

thus, using meaningful names you can (never say never) avoid commentig actions, which makes you intention comments stand out

"[...] that makes the essential comments disappear in the haze."

Yes, the primary goal for any author is to begin with figuring out who the intended reader is.

And writing comments that duplicates the actual action of the code indicates that the intended audience is the coder himself - and that the coder isn't really 100% convinced that the instructions are really doing what he/she thinks/hopes they will do.

In my world, the software comments should be directed at a reader who are already reasonably well versed in the used programming language. So only when something tricky is happening would it be meaningful to augment the code with some explanation of the actual actions (assuming the code can't be rewritten in a way that the trickiness can be removed without introducing other issues).

But I think the schools are failing when teaching programming since they more tend to teach "the code should be well documented" as meaning "there should be a high amount of comments".

It's so trivial to do:

delay_ms(1000); // delay 1000 milliseconds

and explain the action instead of telling the reader why there is a need for a one-second delay - or if the delay time was arbitrarily selected and 500ms or 2000ms would have worked just as well.

And writing comments that duplicates the actual action of the code indicates that the intended audience is the coder himself - and that the coder isn't really 100% convinced that the instructions are really doing what he/she thinks/hopes they will do.

Not sure I can fully agree with that.

Quite frequently I will write comments that indicate what the code is doing; not at the 'load index with 10', but reset index or some-such. In your eyes it might look like simple duplication, but there are many, many times where looking through the code afterwards (maybe years later) has highlighted a difference between code and comment; which has then caused me to re-think what is happening. It's essentially a double check for the mundane and it is something that has certainly worked well with the projects I've been involved with.

not at the 'load index with 10', but reset index or some-such
in my school index = 10 and such is outlawed
index = CHARACTER_LOOP_COUNT accomplishes exactly what you refer to without a comment

one of the most frequent causes for what I call "superfluous comment" is "magic numbers", if you did not use :magic numbers" less comments would be needed.

I am all for comments, but quoting Per "commenting does not just mean lots of comments". Using meaningful names makes a lot of thus useless comments disappear and then the meaningful comments will not disappear in the haze, but stand out.

Magic numbers are certainly something to be avoided, but manifests are definitely not always the best solution.

Many is the time I've seen someone write something like mov uart_ctrl, UART_ENABLE_TX .Code looks fine, people say it's self commenting. But then it's wrong. Nothing is there to say that it should be an or operation rather than a mov.

  index = CHARACTER_LOOP_COUNT

Fine if you only happen to have one requirement for such a value in a module. Not so good if there are a number of them there. Too easy to devise clever names as:

#define CHARACTER_LOOP_COUNT1 10
#define CHARACTER_LOOP_COUNT2 107
#define CHARACTER_LOOP_COUNT3 19
#define CHARACTER_LOOP_COUNT4 33
#define CHARACTER_LOOP_COUNT5 27

I'm wary of people who insist on tight rules. We have recently had [another] new development lead. He insists that we all train up and learn his current best practices. Trouble is, his code always seems to fail. Of course, it's never his current best practices that are anything to do with it and he would rather blame all other code that doesn't follow his practices. So far, his fail score is way higher than mine!

The only absolute rule is that there can be no absolute rule - an inflexible tree snaps in the storm.

But the general idea is to know and understand rules before starting to bend them. It's much better to cherry-pick what works well than spending the day trying to hammer down a square peg in a round hole.

#define CHARACTER_LOOP_COUNT1 10
#define CHARACTER_LOOP_COUNT2 107
#define CHARACTER_LOOP_COUNT3 19
#define CHARACTER_LOOP_COUNT4 33
#define CHARACTER_LOOP_COUNT5 27

should be something like
#define FETCH_CHARACTER_LOOP_COUNT 10
#define IMAGE_CHARACTER_LOOP_COUNT 107
#define RESPONSE_CHARACTER_LOOP_COUNT 19
#define COMPARE_CHARACTER_LOOP_COUNT 33
#define DISPLAY_CHARACTER_LOOP_COUNT 27

your version STILL uses "magic numbers"

oh yes, I have seen this "workaround":
typedef enum
{ONE, TWO, THREE, FOUR}

the idea is that you dismiss those that play games like this