The way I do it is to write what I would be saying as an explanation of what I am doing to someone looking over my shoulder who knows the programming language, making sure I do not lose him.
My memory is quite good, too - and I also remember pieces of code I have written 20 and 30 years ago. But I do not remember everything I wrote over the past 20-30 years, not a chance. I have not counted recently but it must exceed 50 megabytes of sources, there simply are things I have forgotten I did at all, let alone how and why :-).
Writing comments is *something* like writing a (good) manual. Ideally, you want to present information in a manner that allows a newbie to be led "up to speed" on the specifics involved. And, at the same time, don't want to burden an experienced user (who just needs "reminding").
I.e., often, different documents (manuals) are prepared to address the different types of readers. But, with source code, we're stuck with *one* document to address *all*.
[The analogy falls down because a manual typically has to assume some readers know *nothing* about the subject matter!]
Then what do you expect those readers to do when they encounter your tricks -- skip over that part of the code?
If I do something "too clever", I fall back on the "Here there be dragons" preamble -- letting myself and others know that the following bit of code needs to be parsed carefully. I.e., if you're just trying to "see what's going on" in the code, feel free to skim/skip over. But, if you really are trying to understand the nitty-gritty, then take *careful* note of what follows.
B5000/5500 were interesting machines. Really sad to see how so much of that innovation "was unsuccessful" (in the market)
As I now put back together, that was the "for my eyes only" case.
I suppose one never can be sure that no-one else will need to see something, but then I might have a chance to add more comments before someone else saw it.
I suppose so. Or I might not even realize how strange it is.
Yup. *Terrible* feeling to look at something *you* wrote and not be able to recall *why* you "did it *that* way". I.e., have you
*learned* something since then that has caused you to favor a different approach? Is this just a "stylistic" change? Or, is there something that isn't immediately apparent lurking in that implementation that protects it from some sin...
[Best wishes for the coming New Year!]
I will sometimes write throw-away code, and, to encourage it being thrown away by anyone other than me who uses it (including future-me), I will leave off _all_ comments, except maybe a comment that says
// This is test code, lack of comments is deliberate
or perhaps
// we don' need no steenking comments
--
Tim Wescott
Wescott Design Services
http://www.wescottdesign.com
I write plenty of throw-away code when exploring some ideas and avenues of thinking that may or may not lead me to a problem. I still write some comments with that code and mark it down as an exploratory artifact. Sometimes, the code is just playing around with a wild notion.
The one thing I make certain of is that this prototype or throw-away code never enters the production code stream. I just take the resultant information and write a better specification for the code that will be in the production release (which is subject to very robust review and test).
--
********************************************************************
Paul E. Bennett IEng MIET.....
Forth based HIDECS Consultancy.............
Mob: +44 (0)7811-639972
Tel: +44 (0)1235-510979
Going Forth Safely ..... EBA. www.electric-boat-association.org.uk..
********************************************************************
You also can never be sure that *you* won't later want to consult that code (and have forgotten salient aspects).
A long time ago in a galaxy far away I hacked together a little piece of code to reverse engineer some PLA's that were being used to protect a piece of expensive software (i.e., a "hardware key"). The PLA's essentially were just implementing FSM's that appeared "complex" to casual probes (but the licensed software "knew" how the PLA's would respond to seemingly random stimuli).
I was discussing this with a friend several weeks ago as an example of an approach he could use in a project with which he was involved. The approach he was planning on taking was far too naive -- the algorithm I had implemented was much more efficient. (And, much more deterministic -- his approach could lock up with certain types of inputs).
That evening, I dug through my (paper!) archives and found a printed copy (the original source only lived for a few days -- once I had reverse engineered the PLA's, it had outlived its usefulness).
The code is reasonably clear for something I'd written several decades ago (though I can see stylistic changes). And, very *few* comments. The code is largely "self-documenting":
/* find an intermediate state closer to the destination state */ for (place=MINSTATE; place If I do something "too clever", I fall back on the "Here there be dragons"
You want to deliberately cause the reader to "stumble" (hesitate) so he doesn't read things *into* the code that aren't really there. E.g., seeing "
This is the risk. It's *too* easy to take some "found code" hiding on your machine that (*almost*) works (at least it did so good enough to satisfy those initial "experiments") and use that to jump-start some *real* code.
Without comments, you're likely to misremember what the code *didn't* address in it's initial, tentative implementation. As the piece of code *grows* (size/complexity), there is more of a temptation to salvage it ("I'll just ADD some error checking here... and here...").
When I am "playing", files get names like "{foo,baz,ttt}.c". As I often get pulled away from a project for short periods of time, any files having these names will almost always get deleted when I return to the project -- because I can't recall *enough* of what I was doing with them to resume those investigations.
I've also found IDE's and modern debuggers to make this a lot easier. Instead of investing a fair bit of code in gathering arguments and parameters from the user (i.e., "me" during these efforts) *and* pretty-printing results for easy interpretation, I can just start the routine with a breakpoint at "main()" and *stuff* values into specific variables. Similarly, after running the code to "almost completion", I can use the same tools to examine live variables without having to write/print their results.
I.e., it encourages me to NOT invest much in investigatory code so I am VERY willing to err on the side of throwing away an "unfamiliar" file instead of trying to salvage the work it represents.
I also do that - I mark it as "to test" (choice of words must have been made in some desperate moment....:-) ). If a single line, this is the sole comment, it is supposed to not survive the day. If more, I put a comment line "to test" at the start and an "end to test" at the end. If I want to leave that code in the source I isolate it with a conditional line, like ifeq 0 test code endc Easy to switch on and off etc. Once or twice I threw away more than "to test" code; I felt bad about deleting it (had been rewritten though it was not that bad) so I left it after the "end" statement (so the compiler/assembler ignores it).... :D .
I wish I could say I have never found "to test" lines in code working and untouched for years though :-).
But my best was to dig deep down to the lowest system call level of something which did not work under some circumstances - on a system which had been working for years (may be 5, was about 15 years ago). After _some_ digging I located it- was an "RTS" (return from subroutine) line, comment on it being "until written" :D :D .
I never mark code "To Test" because I am able to test each fragment of code as soon as I have written it, so I know it will do as I intended very quickly. However, my development process will see the code (if meant for production) placed under close scrutiny and individual testing to determine that it meets all its stated requirements within the defined limits.
This sort of statement begs me to ask if you have looked at improving your development process.
Which highlights a lack of robust enough review.
Systems I deal with are usually deeply embedded. I will be highly unlikely to see a product again during its operational lifetime (usually 25 years). It just has to work properly with minimal chance for maintenance access. For one project I am looking at at the moment, the cost of equipment retrieval
such a retrieval performed for a fault in code that I cannot communicate with directly (by design).
--
********************************************************************
Paul E. Bennett IEng MIET.....
Forth based HIDECS Consultancy.............
Mob: +44 (0)7811-639972
Tel: +44 (0)1235-510979
Going Forth Safely ..... EBA. www.electric-boat-association.org.uk..
********************************************************************
Well in the world I live in I have to test how things work sometimes. To test if the hardware responds in the way I expect it to, to see how execution times are influenced by this or that - on pipelined machines you just have no other option but "to test" etc. etc. The correct choice of words of course would have been "while debugging" but many years ago I chose "to test" instead - and now I am used to search for it etc. If you have understood this as "code yet to be tested" you have misunderstood it completely.
So how do you deal with code you add to 5 or more years after you wrote it. Say you add a new system call to the OS or new functionality to an existing one.
I have - and I would put the robustness of my code against anyones any day you choose. But your statement is probably because of your wrong interpretation of what my "to test" means, as explained above.
I would say it highlights the fact that we are talking about different worlds.
I call these "tiny software efforts" (a few hundreds of kilobytes sources) which take up to 6 months of my time. I do not do many of them but I have done several over the past 25 years; none of them has ever malfunctioned because of its firmware, in fact I cannot recall witnessing a COP watchdog reset occurrence on any of these.
The event I described was meant also to demonstrate why comments are a necessity. Without that comment I would have had to look at plenty of other code to grasp why the system call just returns under these conditions; the "until written" showed me immediately that I have left this for later, when I need it. I do not remember exactly what it was, I think it was something in the file system, may have had to do with setting the file position on certain file types if my memory is correct on where it was, but it was certainly nothing interfering with the proper work of the system - until some application wanted to go exactly there - which happened some 5 years later, my comment helped me remember what and why and that was that.
I find this an extremely good discipline: leaving explicit "marks" in the code when you *know* you aren't finished with it. Sure, "Unit" and "Final Test" will eventually catch these things (*if* the test suites are well built). But, it is a big productivity enhancer to get in the habit of leaving specific "tags" in your code as you are working on it -- as a reminder/marker to come back to it later.
I.e., we *all* get pulled away from our work from time to time. Whether it is to address some entirely different matter (boss has an urgent project that needs your attention; washing machine is leaking; etc.) *or* just a natural consequence of the development process (you chase down some other aspect of the code and forget that you've got unfinished business where you started!).
"XXX FIXME" is a common flag. You can grep your source tree for "FIXME" and quickly find all instances. Historically, I've used my initials to tag things that are "me-specific". But, that also causes lots of hits on notes that I'd tagged with them (on sources shared with other developers... i.e., "ask Don for further details")
In *no* case should the string "FIXME" appear in sources at release time -- a crude test to ensure you've not violated process!
In which case I misunderstood your post. I had, in fact, read it as "code yet to be tested".
With the types of systems I deal with, that is a very rare occurrence. More likely I shall be developing a completely new system based on the old specs with some new additions. I can re-use some code, but the code I re-use is from a library of former production grade code that is fully documented (and certified) on a "Component by Component" basis. This applies to the smallest portion through to the whole former application. Even in re-use we go through the certification procedures to ensure that the re-use is fully validated.
When dealing with new and un-tried hardware I have prototyping code that is at a reasonable standard but not considered for production quality code. This code is used to gain better information about the hardware interface and ensure that the full details and behaviour are known and documented. This document then becomes the specification, fully reviewed and HAZOP'd to ensure that the requirements comply with the quality needed to proceed to coding. Generating production code from here (or deciding to use library code) will be fairly straight-forward complete with appropriate guards and assertions in place.
[%X]
I think we are clear on my misunderstanding of your post now.
Probably. My world is that of "Safety Critical Systems", usually in quite harsh environments.
In which case we have similar in-use experiences.
On the necessity for comments we are in full agreement. My source code includes the statement of requirements for each and every sub-routine, written before the code is generated. The review performs Fagan Style Static Inspection, Functional Testing with 100% logical path coverage and Limits Testing (this latter testing regime is real stress testing of the sub- routine featuring beyond specification input stimuli). In my development process I am aiming at the "Correct by Construction" goal that is beyond CMMI Level 5.
--
********************************************************************
Paul E. Bennett IEng MIET.....
Forth based HIDECS Consultancy.............
Mob: +44 (0)7811-639972
Tel: +44 (0)1235-510979
Going Forth Safely ..... EBA. www.electric-boat-association.org.uk..
********************************************************************
It doesn't matter what flag you use, as long as you check it.
But really, a thorough test system should create every situation where an assertion fails, and you should also use a "test_pending" assertion that reports any pending (incomplete) implementation in your test report, the same way you should report tests that are currently known to be failing (fix_pending in the test itself).
Comments in the code are a poor substitute for contingencies reported in the test results.
... withing reason. E.g., "XXX" has proven to be a *lousy* flag, IME. It appears in too many other instances "legitimately". OTOH, "FIXME" only seems to have application to indicate something that "needs to be fixed".
Note that "FIXME" doesn't imply that the code is broken or will fail the functional tests! It could indicate the commentary for some portion of code needs to be cleaned up. Or, the code itself may be "ugly". Or, the algorithm chosen is less than ideal for the circumstances -- with undesirable time/space costs. Or, the tag may appear in a "disabled" code stanza. Yet, none of these things preclude passing an exhaustive test suite!
E.g., my gesture recognizer has many such instances scattered throughout it (though it's not released code so "that's OK" :> ). Places where I can exploit some specific knowledge to short-cut large portions of an "equivalent" algorithm (but haven't yet had time to implement).
However, IMO, it is "bad form" to release code with such "notes" in it. It's as if you've not truly "finished", yet.
(OTOH, it is surprising how often you encounter this in released sources!)
I have seen others not having such good answers, including cases of "we never thought of that."
But even that case, the hardware will be another 35 years older! I think a good case can be made that just parts availability will increase risk of staying with that hardware over the costs of certificating new hardware and software. Otherwise, I hope they have a large stock of spares!
Whether the higher ups agree is another question, but I would consider it my responsibility to present the alternatives.
But that only extends to the point at which the code leaves *your* (our) hands! The next mutton-head can make all your efforts for naught (e.g., REMOVING your comments from the code in lieu of having to UPDATE them to reflect his/her changes).
I *expect* (hysterical raisons) folks to be lazy and not disciplined enough to keep documentation up to snuff. So, I've tried hard to make the "easy path" the "right path" for those folks. I.e., so that it is easier for them to fit within the framework I've laid out than to circumvent it (which leads to its inevitable deterioration).
E.g., the test-to-sound rules in two of my speech synthesizers are basically simple pattern matching algorithms: *this* combination of letters leads to
*these* sounds. Hysterically, these sounds were represented by combinations of ASCII letters (because the special symbology of the phonetic alphabets were not available).
So, vowels might be encoded like "AY", "OW", "IY", "UW", etc.
To someone not "skilled in the art", it is way too easy to misread these graphemes and subconsciously translate them into the WRONG sounds. For example, "hay" (i.e., dead grass) is phonetically "HH EY". By contrast, the phonetic representation "HH AY" is "Hi!" (or high).
Rather than risk someone making a "careless error" in marking up the code -- or, failing to update the commentary accordingly -- I have taken an approach that makes it very hard for folks to modify the rule encodings (it's not a trivial process due to the efficiency required of the algorithms).
Instead, I have a *document* that describes the algorithm and enumerates the rules (large tables). In those rules, each sound is represented by a special "phonetic" symbol (this is potentially ambiguous as there are many symbologies developed over the years to represent specific sounds). So, that "AY" really appears as an 'ai' glyph... where the two "letters" are crammed together in much the same way you would see "ae" in the spelling of encyclopAEdia; the "HH" as 'h'; the "EY" as 'e'; "OY" as a small caps IC rotated 180 degrees; etc.
The point of this is to remind the reader (who is also the guy opting to hack the code!) that these aren't "letters" but "sounds". Additionally, examples of each sound in "common English" words are presented. And, finally, actual *recordings* of the sounds from the synthesizer. I.e., THIS symbol makes THAT sound!
The developer updates the tables in this (~50pp) document using the symbols that are present in the document. *THEN*, a tool that I wrote extracts the tables from the document and builds the "include" file for the executable.
Of course, there is no guarantee that the future developer will NOT change the algorithm and fail to update all of the PROSE in the document. But, if he changes the algorithm so that the encoding of the ruleset is altered, he'll have to rewrite the tool that parses the document as well. At that level of involvement, he would probably opt to just discard the document entirely and develop some alternative scheme ("Hey! Let's use 'AY' for the 'eye' sound, and 'EY' for the 'ay' sound, and...")
My point: make it easy for folks to make changes that remain consistent with the documentation and discourage them from those changes that would result in the comments being invalidated (or elided!)
Which is why I elided so much of your response, here. I really don't see a GOOD answer. All the effort "spent" on novelty languages over the last 50 years with very little result in terms of embedding semantic content in the languages developed in a "humanistic" way... :<
In practice, it makes sense to recertify upgraded new systems every 20 years if your intention is to run the plant for 40-100 years. Especially the RoHS makes maintaining a spare part inventory quite hard.
ElectronDepot website is not affiliated with any of the manufacturers or service providers discussed here.
All logos and trade names are the property of their respective owners.