i have problem with the led blinking. I using the exmaple program given by keil using uVision3. When i run the program, the LED on the development board didnt blink, it just stay on! wat should i do?
thanks!
No, my answer was not critique about your suggested name, but a continuation trying to explain why people should not think that a long name equals a good name. Everything is about context. And why people should not think that foo() is an acceptable name as long as there is a one-page comment describing the foo() logic directly above the implementation.
Writing too much is a very common error - most people who send in their first school assignment are scared to death about software comments. So they document every single code line, completely duplicating the software function in two different languages - but often with the comments describing a previous version of the application :).
How many have seen the following assembly code?
MOV A,0 ; Set register A to zero
Might be ok in a book teaching assembler, where the example is intended to let the reader learn the mov instruction. But as a comment in a real program, it does not supply any extra information. The reader still don't know why it is important that A is zero. If A is used as index into a text string, it might help to tell the reader that "start from first char in string".
I shall take a section of the Rules for Code Monkeys book I wrote many years ago about "comments" to help others figure out what a comment is.
(Rules for Code Monkeys is an internal document like the coding guidelines you have there at work: that open copy right next to your keyboard).
************
Generally "Comments" can be categorized as Tactical, Strategic, or Theater-Level. (The Theater Level can be termed Theatrical, but in the "Theater of War" sense and not the Showboat sense).
Theatrical comments are typically found in the file's header, and shall describe the purpose of the module, and how it may fit in the theater of operations for the Computer Software Configuration Item (CSCI). The CSCI is known as the final 'executable' file.
Theatrical comments provide the reader a higher level of understanding of the software and typically reflect the Software Requirements Specification (SRS) from the coding standpoint. Theatrical comments can be found anywhere, and do not [currently] have a flower-box identifier to indicate such comments. The most obvious location is within the module header information.
Theatrical comments provide the reader with a wider conceptual view of the code module. Theatrical comments can be information about the system's environment like the OS, CPU, Memory, IDE, Versions, etc. While Strategic and Tactical are the dominant forms, Theatrical comments should be still be contained in all source code modules. Source code also includes batch files, linker support files, and anything else that is required to cleanly build the CSCI besides the cross-compiler itself. If the IDE requires startup files, then those too should also be considered source-code and commented accordingly.
Strategic comments describe what a section of code is supposed to accomplish. Strategic comments should be placed before the code section that implements the task. This includes the function header block. At the function block, these Strategic comments identify the scope of the function, the expected method of accomplishing the task, the passed parameters, the return value, and any special notes the software engineer should know about the function. These notes may include such items as measured execution times, atomicity, or any other code-centric information that the software engineer should be aware of when modifying the function.
The more common Strategic comment has an enclosed flower-box describing the intent behind the following code. The code itself should be clear enough through liberal and consistent white-space usage, and data-store (aka 'variable') name selection.
Strategic comments should precede most control flow operations, and alterations of CSCI states. (e.g. if(), else, while(), or the enabling of interrupts, or data-store assignments that implement what the code is supposed to do).
Strategic comments should be the primary and dominant form of commenting source code.
Tactical comments describes the specifics on how the code is implementing a task. Typically these tactical comments are on an end-of -line basis. (For 'C' it would use the double-slash // delimiters).
Tactical comments serve to enlighten the non-obvious behavior or method implemented, and not simply a re-statement of what the code performs:
i = 0; // assign zero to i <---- poor comment i = 0; // start indexing from zero <---- a better comment
The over-use of tactical comments will result in source code that takes too long to read, and begins to devalue and hide the worth while comments. So the above example typically wouldn't be commented.
Tactical comments should be as detailed as needed to inform the programmer. The common used for Tactical comments is when describing the side effects of code implementation or when the code performs something that is not obvious to the standard or novice programmer. Always write on a level that is explanatory the reader, and never assume the reader is as competent as you think you are.
Enjoy,
--Cpt. Vince Foster 2nd Cannon Place Fort Marcy Park, VA
I have a template of stuff, one of which is the function name template.
This has the elements that I think are important to source code. IMHO.
/* **====================================================================== ** Function_Name [catagory] [spec tracking numbers] **====================================================================== ** ** Function comments ** **---------------------------------------------------------------------- ** ** Parameters Passed: <void> ** Parameters Returned: <void> ** Notes: ** **---------------------------------------------------------------------- */ void Function_Name( void ) { . . . }
An example of implementing this template into the real world... well I made this up, but it is a typical construct...
/* **====================================================================== ** Keil_Example [ CALC ] CSC8 CSU8.2.1 R4 **====================================================================== ** ** This function shall scan the array for the specified value, perform ** the simple pattern masking for validation. Based upon that 'match' ** compute and return it's corrilation factor. ** ** Add more description text here to make it thorough enough, but not ** too thorough that the code-monkey ignores the design documents. ** ** It helps to make reference to the design doc ** ( e.g. "reference table XYZ for details on return format" ) ** **---------------------------------------------------------------------- ** ** Parameters Passed: ** ** u8 val - value to search for within array ** u32 *arry - array to parse ** u32 pmask - pattern mask for validation ** ** Parameters Returned: ** ** s16 - corrilation factor: internal fractional binary format ** ** Notes: ** ** CAUTION: Contains a polling loop with no safeguards to protect ** from an infinite loop if the hardware fails! ** (needs a time based break mechanism) ** ** As of 04-Dec-08, this routine takes way too long. ** Need to optimize the algorithm. Suspect the array indexing ** is taking too long. FIX IT! -- Cpt. VF ** **---------------------------------------------------------------------- */ s16 Keil_Example( u8 val, u32 *arry, u32 pmask ) { . . . }
Things like date created or author of the function, to me, are irrelevant, since the module header contains this information on when the module was edited and why... and who was responsible for the changes.
The repeated function name in my header is important, along with the tags 'category' and the document referencing labels. Although your IDE/editor might not explicitly state that it uses the DOS 'grep' function, it has the same result.
grep CALC *.c > calculations.lst grep DIAG *.c > diagnostics.lst grep UTIL *.c > utilities.lst grep CSC *.c > requirements.lst grep MUTATOR *.c > mutators.lst grep ACCESSOR *.c > accessors.lst
Your document references allow you to quickly identify where in your source code *you think* you are fulfilling the requirement(s).
As far as naming conventions go, all will fail. Most fail equally well. Do what you think is right. You'll get better at it in time.
Hungarian is a total waste, so don't go down that path.
Naming conventions become important for accessors and mutators (crossing module boundaries), while the internals are far less important.
That delay_ms( 10 ) function looks to me like an internal (module specific) function. A more formal type function name to me would look like TimeBase_Delay( 10 ) where you might infer that the time base module contains this function, and you must look into it in order to know that the passed parameter is in milliseconds.
Don't get me wrong, I'm not advocating that cross-module accessors & mutators have start with the module name. That is up to you. I usually don't do that. But I do use Upper_Case function names as potential cross module functions while all lower_case function names are internal service types. That's just me and not something I advocate others implement in a coding standard.
It is not "TimeBase_Delay_ms( 10 )" for a reason: I would use this format:
TimeBase_Delay( DEBOUNCE_DELAY );
and in the definition of the constant, I would have determined the function needs (milliseconds), while the code that called the function knows that it must call a delay function, but not need to know the delay is in milliseconds, microseconds, or some fractional hour format.
The delay_ms( 10 ) is kind of missing the point: you are delaying 10 milliseconds for a reason: make that reason clear to the poor slob who must maintain your scrawlings:
delay( SCREEN_REFRESH_TIME );
Anyway, I've rambled on too much again.
It would be quite interesting the see the full code monkey rule set.
Swatting magic numbers and instead use constants is the next step up, when people have considered their use of symbol names and how to comment their code.
Doing the swatting first would probably result in:
enum { N = 17, // N=18 seems a bit excessive. M = 12, // Use 12. ... }; wait(N); // need to wait
or possibly introducing broken defines:
#define M 12 #define N M+5 wait(N*1000); // us
#define N M+5 Always( always( always ) ) use parenthesis.
#define N (( ((M)) + ((5)) )) // (over) (use) (them) (!)
Its in the book; on page( PARENTHESIS ) to be exact.
Its basically standard stuff; a racy jacket, a steamy intro, the main characters are shallow, has a thin plot line, lots of typos, and has a dry, monotone-ish narration.
In the end you are either a satisfied or you're left needing more.
<excerpts from "Rules for Code Monkeys"...>
Thou shalt not use Hungarian Notation. Thou shalt not use 'internet' code; unless an assignment is due, and the teacher can't tell the difference anyway. Thou shalt not kill (depending upon the project specifications) Thou shalt not use the closing bracket ']' symbol without first declaring allegiance to King Kong or saying several "Hail Fay Wray"s. Thou shalt not ramble-on-and-on in forums. etc.
You know, the standard stuff.
Yes, I know that you hate macros.
I felt that I had to write that example just because the people in most need of good advice about symbol names and sw comments are quite likely to do produce such #define'd constructs.
A #define'd expression without parentheses is definitely one of the mortal sins of programming - it doesn't matter if it is production code or just some test code.
Another is to hide the #define'd symbol by not using capital letters.
Or having a conditional #define that mucks up a dangling else. Or writing code that has a dangling else.
A define that makes use of a parameter more than once is also quite high up on the no-no list. And code that does call a #define while using ++, -- or similar modifying accesses on one or more of the parameters.
I haven't really decided what is the best way to get good developers. - Huge quantities of information. - Give people a bit of help into all kinds of traps and then have them learn why they got into the trap and how to avoid at least that speficic pot-hole in the future.
In the end, hands-on experience with problems is quite efficient. People tend to remember a broken nose far longer than they remember the text in a school book. And they don't doubt the real pain that results from doing something the wrong way. The trick is to not produce permanent damage so they switch to another profession, and not to produce permanent monetary loss.
Yes, I have seen
#define TEN 10
Now that is a real beaut.
I just hope it was from a very bright student who wanted to be a bit cheeky with his teacher.
I once saw some source code where the person didn't realize that decimal and hexadecimal is just different presentations of the same number, and that the C compiler supports hexadecimal constants.
So the code contained:
#define HEX_00 0 ... #define HEX_A0 160 #define HEX_A1 161 ... #define HEX_FF 255
Good to have in case he needed a hexadecimal number and forgot how to translate to decimal :)
Or maybe he had seen one of the binary declarations that exists here and there, and not realized that a header file with:
... BIN_0110_1001 0x69 BIN_0110_1010 0x6a ...
exists just because binary numbers aren't part of the standard language, while the compiler has very good hexadecimal support directly in the language standard.
So i have to use the delay function inorder for this to work? But how do I create a delay function with AT89S8252?
Next thing, How do i ensure that my development board is correctly connected other than using the blinking code for testing, are there any other code which i can use for testing?
Thirdly, I have use meridian software to connect the development board, But when i select COM1 port, the active light will go off and I cannot chose the device from the list. Is this normal?
The board that i am using is EQ-8051-ST1 is a AT89S8252 chip, which i see from the board.
Thou shalt not kill (depending upon the project specifications)
captain, what about the three rules of robotics... ;-)
They will not be introduced until the positronic brain has been released.
By the way. Asimov later extended with a fourth rule about the good of the many, to avoid freezing and permanently destroyed positronic brains ;)
and, of course, he later introduced the "zero law" as well.
ho, you meant that one!
About PCW, I want to know the hexa code for this thing so that i can configure the output of the port. Because I heard that I need to configure the port so that I can make the LED blink
What is PCW?
Your subject "RE: PCW" seem to imply a continuation of an earlier discussion, but PCW has not been mentioned anywhere earlier in this thread.
Are you talking about the PCW C compiler?
If a 'robot' implements Asimov's three Laws, its OS was most likely written by Microsoft, Apple, or Ben & Jerry's All Natural Coding Company.
Elsewhere, especially in the despot 3rd world like North Korea, or any communist country, Asimov's Law wouldn't be coded up with zeal.
The real-world variation to Isaac Asimov three laws of robotics is the "Kim Jung Mao Tse-Stalin" Three Laws of Robotics:
1. A robot may not injure a human being or, through inaction, allow a human being to come to harm. 2. All Robots are to comply with The Higher Utopian Government (THUG) 3. Rule 2 supersedes Rule 1.
My rule-book against [coding] radicals does have a Human Safety Factors Section. No reference to Isaac though.