To continue our series of tips on using Make and Makefiles. Something that I've observed on occasion in top level Makefiles is this construct:
make -f widget1.mak make -f widget2.mak make -f widget3.mak
The proper way to write this, is:
$(MAKE) -f widget1.mak $(MAKE) -f widget2.mak $(MAKE) -f widget3.mak
That is recursive 'make' commands should always use the variable '$(MAKE)', not the explicit command name 'make'. Using recursive Makefiles properly run faster and do not suffer from hair pulling macro expansion problems in the nested Makefiles.
That would make for a rather short blog entry, so lets expand on the root cause of the problem. Did you read the manual for Make? Ever?
What is the secret tip to faster development? Like most things it is a simple one: Read the manuals for your tools, be it the new O'Scope you just bought (Did you know about the Badger and Games in the HP 54645D? Only reading will find them.), or the development tool(s) that you have been using for years. Have you ever read the excellent manual for Make for example? Ever read the manual for EMACS? GCC?
Alas far to many programs and projects suffer from no documentation, or worse yet, wrong/outdated documentation. I've always found that writting the documentation for a project before code is even considered makes for faster development, a more robust product, and stops the problem of "we'll get around to the documentation someday" after the code ships. Don't over look tools like Doxygen to help out.
Audrey Watters recently wrote Tips for Writing Good Documentation. Has links to several other guides to creating documentation, and helpful tools. Checkout the comments at the bottom as well.
If you are serious about writing good documentation, and for that matter code, make a trip to your local library and checkout a copy of the Chicago Manual of Style.
One final tip on documentation:
Read It Seven Times
9 September 1985
Z-NEWS 302
Echelon, Inc.[*]
Los Altos, CA 94022
[Now out of business, outdated info removed]
Z-News 302 is Copyright 1985 Echelon, Inc. All Rights Reserved. Permission to reprint, wholly or partially, automatically granted if source credit is given to Echelon.
WOW! again: Foot put into mouth! Suggesting (in Z-News 209, pg 2, first line) that everyone read material seven (7) times, without simultaneously giving full explanation of why, has been big stumbling block for many. So we deliver details to remove those (mental) blocks; remember, read through explanation (and everything else) seven times:
Readings 1 and 2. Skim material twice, quite rapidly. Use your finger to help your eyes play over words, lines, and paragraphs. Key words and phrases, ideas, and concepts begin to take from. You gain a feeling of the thought-flow, a framework making next step more powerful.
Reading 3. Read material now from beginning, much more slowly and carefully. Pause to re-read and ponder new ideas and deep thoughts. Use dictionary for unfamiliar words.
Readings 4 and 5. Skim over material twice again, but not quite so rapidly as first two times. Let key concepts sink in even deeper. This is a more leisurely skim. Pause at any word looked up in dictionary and make sure you know both basic meaning of word, and its meaning in present context. Sometimes the thought expressed by a particular word or phrase is so new that it's difficult to grasp at once, even with dictionary help! Do not worry at this point. Future readings add clarity.
Reading 6. Now, read material from beginning again with extreme care. Now is the time to really pause, to ponder, to digest, to impress deeply. Try to obtain essential, inner feeling of messages, even though you may not understand them fully or grasp completely at this stage. Try at this point to read material aloud!
Reading 7. It's a slow skim. Somewhere between your leisurely skim and your first careful reading, #3. It is time to enjoy, to bathe yourself in new insights and viewpoints opening up to you...new understanding comes (in next octave)!
There you have it--we do our best to explain. Never think that learning something new, really new, comes quickly or easily. GREAT EFFORT IS INVOLVED! But keep reading even if you think you don't understand--what comes later (down the lines) explains what came before, following natural back-and-fill (smoothing) concept.
*: The Echelon above has no relation to the purported NSA Echelon spying project, nor the Echelon company that has always sold interesting control networks for buildings with you've got to be kidding prices for the development tools anytime I looked in the past.
Posts
No comments:
Post a Comment