We are running a survey to help us improve the experience for all of our members. If you see the survey appear, please take the time to tell us about your experience if you can.
The other day, I was doing some consulting for a company on their overall design approach toward a solution. I found that one of their engineers wanted to implement a MCU design in an FPGA versus doing a more traditional discrete MCU with the standard support ICs, etc.
The product was never going to go into high volume production and the electronics cost was so small compared to the rest of the system that the effort to move the MCU into an FPGA seemed more of a "fun thing to do" rather than a rational thing to do.
I told the owners of the company that if they went down the MCU/FPGA path, then they would tie themselves into the type of talent needed to support the FPGA MCU rendition of the design versus the more commonly found MCU embedded pool of talent that they could hire.
This is a subtle but important decision as it binds the company to that particular engineer's talents, or they would be faced with hiring a specifically skilled FPGA engineer at a higher cost if they were to 'lose' the original engineer (due to resigning, etc).
The owners/bosses really were excited over my point about tying their system into a too 'niche' type engineering cycle and sole-sourced talent.
A more traditional approach would be advised in this case as there wasn't much of a difference otherwise.
I am sure (pure speculation) that the engineer who wanted to move the MCU into the FPGA fabric was excited about doing so. After all, given the chance to expand one's abilities and add to their repertoire of talents is indeed exciting.
Then I thought about how his boss was going to quash this approach based upon my advice. If indeed this engineer was excited over his approach, I'm sure he was equally disappointed to have to give that up.
As you know, I'm rather wordy, but this brings up a point I learned many years ago, when I was hired to complete a project. The Project Manager told me right up front, that if I tried to code "job security" into the system, he would fire me--"as fast as he could."
I completely understood that, and all of the code I've written [before and] since has been done in a fashion that could be easily picked up by somebody else. (well, most of it was).
During that same statement, by my new boss, it was also pointed out that only a boss who can tell the difference between coding-in job security and doing properly written code, can appreciate and retain programmers [code-monkeys] who code to the benefit of the company, and not themselves; and reward them accordingly! (That was an important point !)
A dilemma with "doing it right" versus "doing it quickly" (where quality suffers) can be that in some situations you, as the software engineer, are the only one there at a company who knows the difference. In such a situation, you can see where your own morals lie.
I'm sure you veteran embedded guys know what I'm talking about, especially when it comes to taking on a project that *somebody else* has started.
This is one reason why I insist on doing the documentation to a project prior to doing the code-monkeying. It is far more difficult to design a project so that "only you" know how it works when you've written the proper set of pre-code documentation on how the system as a whole shall work in plain English.
Coding should flow from such documents and not the other way around.
Tools that generate documentation FROM your code, to me, is worthless.
It totally misses the point. An after-the fact documentation of the code tries to explain the code as written, and that most likely will hide failures of the overall architecture of a design... even hidden simply by saying "Yes, it is documented--see." [Note: it only helps if you have already done the up-front documentation and you can compare the source-to-documents against the master set of documents].
Yet if you are forced to forego the up-front documentation (a decree by one's boss) then the code you write should contain enough information in the way of commenting so that if you died tomorrow, the project can still go on and not be scrapped.
Okay, fine... not 'died' but let's say you found a new job at twice the pay and double the benefits. You quit in two weeks knowing that there is no way in hell anybody else will figure out what you were doing.
That project you half-baked will still haunt you when that hot new job goes belly up for some reason. THEN you'll have to rely on your reputation from the company you left hanging.
A burnt bridge and a stain on your resume'.
</rant>
--Cpt. Vince Foster 2nd Cannon Place Fort Marcy Park, VA
I was worried that I would get flamed over my total dismissal of software tools that derive "documentation" AFTER the code is written. I personally have never used such software tools.''Is there a high demand for post code-monkey documentation? There are a lot of companies that offer post part-em "documentation" so I figured that would be the hot-button issue.
Does anybody find such a tool useful?
I think that the day these god damned tools will do any good will be our last day in the business - I mean, if machines would be able to think in order to generate anything but diagrams and silly comments, they would probably be able to write the software themselves...
I was worried that I would get flamed over my total dismissal of software tools that derive "documentation" AFTER the code is written. I personally have never used such software tools.''Is there a high demand for post code-monkey documentation? There are a lot of companies that offer post part-em "documentation" so I figured that would be the hot-button issue. I have seen 'managers' that bought such and, in every case it has been because the documentation that existed was not the kind they preferred. I recall a project that was beautifully documented inside the code and a 'manager' bought a tool to extract that documentation to an external document. The excellent documentation, when left in place, became worthless when run through the chicken machine -- sorry could not help that expression for "mechanically separated".
Does anybody find such a tool useful? Having been exposed to them (not by desire) I do not.
e.g. such a tool will 'extract' some information but you still have to go back to the code to see the relevance of the extracted stuff.
Erik
Not sure, but maybe:
www.mjmwired.net/.../kernel-doc-nano-HOWTO.txt
7 In order to provide embedded, 'C' friendly, easy to maintain, 8 but consistent and extractable documentation of the functions and 9 data structures in the Linux kernel, the Linux kernel has adopted 10 a consistent style for documenting functions and their parameters, 11 and structures and their members. 12 13 The format for this documentation is called the kernel-doc format. 14 It is documented in this Documentation/kernel-doc-nano-HOWTO.txt file.
I use Doxygen a lot.
It is a tool to create indexed documentation on a function and variable level.
The produced documentation can be a great helper for someone when learning to navigate the code.
But this type of documentation is completely separate from the reguirements documents, and from the design documents.
Anything non-trivial should have design documents that describes (before anything is implemented) how things are intended to function. This should also cover things like testability. On one hand - is the produced results repeatable? On the other hand - will the code fulfill the individual requirements? And what will happen for invalid scenarios, such as incorrect or missing input or loads higher than required?
Design documents should exist before the code, and should not be an after-thought attempt at documenting what the code actually does.