Fortunately, this is not a problem today, but after 10 years ...
Even if you hire some person willing to learn COBOL/FORTRAN, for how many years do you expect him/her to stay employed ?
A few years ago there was a company seeking PDP-11 assembler competent person to maintain and train new persons for their spent fuel rod basin until 2050. I considered applying, but unfortunately it was on the wrong side of the Pond :-(
Of course, you can hire a competent person to do a single COBOL/FORTRAN fix, but how do you expect to keep that person employed, unless you have some more demanding day to day tasks ?
I hear from real estate agents that it is the same for house buyers. For one, it was our real estate agent explaining that we would imagine what it would look like, but most can't. Sellers are supposed to make the house look ready to move in, and especially remove junk and excess furnishings. The house we got had lots of junk (it took the sellers two days to move out), had been on the market for six months, and we got it below asking price (18 years ago). (snip)
Too familiar... I always try to figure out the rationale behind a requirement. The "why" is usually more valuable information than the "what" because the "why" tends to be less likely to change and just the "what" without understanding the "why" rarely provides enough information to make a sensible implementation of what is being asked.
Asking the "why" question doesn't make one always popular though. I've had dealings with a customer who got rather annoyed when I asked why they wanted a feature (what is the benefit for you or your customers? how are they gonna use it?). That feature had a rather fundamental impact on their system and implied 10+ man-years of development so I would expect at least some rationale. However that customer insisted that I stopped asking why. Later I found out that that feature was a "sensitive" subject within the company and that they really didn't have a rationale, other than that the new management insisted on it because their competitor had it so they should have it too. That feature made sense on their competitors system as addressed a fundamental drawback of their system concept. However system concept of my customer did not have that weakness so the feature had no real added value; one could argue that it made the system worse. When the project was well beyond halfway marketing requested to have a version of the system without that feature because (surprise!) there was no demand for it.
I have also had a case where it was easy to point out that there was no business case for a (in my option questionable) feature that would take at least 4 man-months to implement:
- Could you sell the machine for a higher price? No.
- Could you sell more machines? No.
- Could you sell your machine to other customers or markets? No.
- Is there any other strategic benefit? No.
- Does it make the machine cheaper to manufacture/service..etc? No.
- How many of your customers would benefit from that feature? We know of only one case, we don't expect there are other cases where this feature would be useful.
- Would that customer pay for that feature? No.
- Would it help to get repeat orders from that customer? No, the decision makers there won't care about this feature.
- How often would that customer use that feature? 1 or 2 times a year at most.
- How much time would that feature save that customer? 5 to 10 minutes at most. A year? Yes, 5 to 10 minutes a year.
So the conclusion was there was no business case but we should add this feature anyway at the expense of features of which the added business value was clear. I guess I should have gotten a MBA or something (politics?) to understand the reasoning.
One of my customers acknowledged that, he literally said: make something I don't want, after seeing that I can tell you what I really want. At least both sides knew what to expect in this case.
As a contractor I work for various customers in several domains. It is often a hassle to get clear unambiguous requirements _and_ their rationale on the table. It is easiest with people who have been in their business for a decade or more who know their domain, know their customers and understand their needs, know every their product(s) and know their competitors and last-but-not-least have a vision where they want to go. However those are rare; far too often I'm sitting with someone at the table who has been been there for just a year or so and barely knows more about their market/domain than one can figure out in a couple of hours. Lack of vision and knowledge combined with uncertainty leads to "fuzziness" and the refusal to prioritize and to make tough choices.
In my book no comments are better than incorrect comments or comments that really add nothing (like the examples above) because they mislead resp. distract. I prefer clear code with few or no comments over heavily commented messy code. One of the coding guidelines I wrote had a rule: "Don't add comments that have no added value". That was for an organization where the rule used to be to always add comments, resulting in 99% of the comments in the code being just noise.
The problem with comments is that they often are (or become over time) inaccurate. I do write comments to describe the interface; what does the function do (_not_ how), the pre- and postconditions, acceptable parameter values, how errors are communicated and the semantics of the return value so one doesn't have to look at the implementation. When some non-obvious implementation choices are made I describe the rationale. When many comments are needed to make clear what the code is doing, it might be time for some refactoring.
How many comments are needed also depends on the programming language; with low-level programming languages like assembler and C I feel more often the need to add some the high level perspective in the comments.
Oh all of it, practically. I make choices regarding my own efficiency based on what I can do, obviously.
I have yet to encounter someone who can't write decent comments to his sources to author something of real value so the language choice here is irrelevant. Of course C would come to some rescue to such a person, non-commented C sources are easier to read than non-commented VPA would be I suppose (never saw any of these :D ), in a way crutches are useful to someone with broken legs.
It _allows_ ambiguity, it is up to the author to put things in an unambiguous way. Of course "most people" can't author text of any significant value. Most people are better off if they have just boxes to tick to express what they want.
Well yes, of course. I mean that the lower the level the less a novice to the language has to learn - but this applies only to the lowest level (i.e. machine code) so I agree with you, there are always subtleties to work on - either in the language syntax or in the code itself (making calls, passing arguments etc. etc.). So having the lowest level available is not much help to a novice as I said earlier, I think I was wrong about that - but it is not an obstacle either.
Well neither of these has happened over the past 20 years so it would have been a terrible choice had I opted to follow into other people's steps and practically prevented myself from doing 90+% of what I have done during these 20 years just because one day I might need help. The company would not have survived to that day; it manages to live only because I have things on offer my competitors do not have. Put me on more level terms with them and I'll stand no chance.
Well my interests do not extend much beyond my own work. If someone would buy my operations (not that I am selling, this is my life and I am 59, not out of plans for future work)it would take may be a year of someones life to get into my work and continue it - which would be about the same whichever the language, most of the work will go into getting familiar with the entire "building". Definitely a bargain taking into account that I know people who have spent at least tens of millions for 20+ years trying to do only part of what I have done - to no result.
I just make it up as I go, usually it is a reference to some other file on my disk, just some file name etc. I have had little trouble locating what I need in seconds when I had to dig into stuff I have written
20+ years ago which means other people would find it as easy, too.
Not really, no. The comments are an integral part of the code, there are comments on practically every line. Typically when I go back I read the comments and look to the left only when I reach the point of interest.
Well of course, who would not like that. I was just saying that I would not put much effort in that because if I had it it would not save me that much time, I rarely have to go far back to such depth (and my memory is good when it comes to what I currently work on). Then may be I am underestimating it, I don't know.
Well pdf-ing the sources.... I don't think I would accept this. If you suggest html-ing them I might begin to scratch my head but I don't think I'll find time for that in my expected lifetime :D .
Yup. Ask of an *employer* and you're an obstructionist, "not a team player", etc. Ask of a client and they feel intimidated -- esp if they can't come up with a ready reason (if there *is* one, they can take it as an opportunity to educate them about their market)
Marketing types tend to see "having more" as better than "having less". They don't see the consequences of this (reliability, development time, cost, extra complexity reflected to the user, etc.) but know that they NEVER want to hear themselves utter the dreaded words, "No, ours doesn't DO that".
(Heck, many software products have salesfolk who outright *lie* about what their product is "capable of doing"... their rationale is probably something along the lines of "Well, if we rewrite major portions of the software, I'm sure it *could* do those things so I'll just say it DOES them, currently!")
If you're being paid T&M *and* don't mind "burning time" on something that is likely to be discarded, that can work. OTOH, client can later conveniently forget all this and start complaining about "how long it's taking" or "how much it is costing", etc. People have selective memories :>
Personally, I don't like "wasting hours" on something just because someone couldn't (or didn't *want* to!) sit down and figure those things out beforehand. I treat hours as "pieces of my life" -- irreplaceable!
Keep in mind that there are often people above the ones you are dealing with. And, the guy *you* are dealing with probably doesn't want to bring "reality" ("bad news") to *his* boss, either. So, he's willing to gamble that it will magically be easier (cheaper, faster) than you are suggesting at the outset. Or, that the project might get canceled for OTHER reasons before The Truth manifests.
I had an employer who was visibly upset with me for finding a bug in a piece of custom silicon (it wasn't *my* design). *I* looked at it as saving them an iteration at the foundry (I found the bug before the silicon was produced). *He* apparently looked at it as "Crap! Now I have to tell *my* boss we'll be late..." (Um, would you rather tell him you're going to be EVEN LATER after you have the defective silicon in your hand? And, the invoice waiting to be paid for that iteration??)
You did not misinterpret me, I also have seen plenty such people. The ambiguity is in how we define "real value", which of course can differ not only from person to person but within the values of a single person depending on his current needs, mood etc. :-).
It is a good point, but it is not the language that is the problem. C/C++ or doesn't solve that problem.
BUT if I was looking at that job, one of my first actions would be to present a migration plan to newer hardware/software. I might be working myself out of a job, but I might even be suggesting it in the interview. Or at least asking: why are you running such an ancient system?
(BTW I loved the PDP/11. I learned my first assembler on it. When I learned 8086 assembler I said to myself "what is this S***?")
It depends on the actual nature and content of the comments. A comment may be correct "in spirit" yet contain "typos" that you can readily catch and correct. Discarding the entire comment because it doesn't *appear* correct "out of the box" can discard worthwhile information.
The hazzard with comments is when you get someone who is too lazy (or, perhaps, not competent enough) to read the code using the comments to
*clarify* what the code is doing. Instead, they read the comments and *assume* the code "does what they say" (which may be what the writer *hoped* the code was doing... but isn't!)
The real risk comes when someone "touches" the code, later, and doesn't want to invest the EXTRA effort to update ALL the comments to reflect the changes he/she has made. Once this process starts, it quickly gets out of control -- making the effort to reconcile comments and code even more expensive.
I've changed my commenting style over the years to introduce more "block comments" than "line comments" just to make it easier for the *entire* comment to be replaced -- instead of having to go through updating a comment on this line, another on that line, etc.
A lot depends on the developer's style. E.g., I use pointers A LOT! So, the results of every pointer arithmetic operation usually can benefit from something descriptive that indicates *what* the pointer is referencing, currently.
I use invariants to clarify the constraints on parameters (in and out). And, now litter the body of functions with invariants where appropriate. Make a change to the code? Turn them all on and re-run the test suite to verify they are still valid and that your code properly observes them.
Moving to ASM almost always increases the verbosity of my commentary. (Most) HLL's implicitly inject some additional meaning into the source. E.g., "int foo" makes it clear that foo is an integer. In ASM, that same location can be referenced as an integer, character, float, list element, etc. -- the ASM opcodes don't impose any (significant) meaning on the "location"/variable.
There can also be subtleties in instruction sets that need to be explicitly clarified ("reminders") so the reader doesn't subconciously assume something that isn't true. E.g., chosing one operation over another "seemingly equivalent" way of accomplishing the same thing... EXCEPT one preserves some flags that the other does not.
But others (businesses, stake-holders, etc.) have to consider *their* interests. If it will "cost" them more (money, time, lost opportunity, etc.) to adopt a different approach, they need to see measurable differences (quality, development time, etc.) in the resulting product.
IME, there are far more "average" engineers out there than "exceptional". Most businesses need to make do with "average".
The advantage of HLL's is they "self document" (gag!) to a greater degree than lower level implementations. Some of this also works for the benefit of the (initial/sole) developer -- "Ah, this is an *int* and not a string!"
I've had to hack my way through some really lousy sources over the years. Disciplining myself *not* to "fix" everything that was (obviously) wrong -- coding style, algorithm structure, etc. -- as that usually wasn't part of the "project" ($$$). The same is true of much of the FOSS sources that I tinker with. It is amazing that when NOT encumbered by a "nagging boss" or an "unrealistic schedule" the quality of the code doesn't *improve*! The same practices permeate software that folks do "on their own time/dime" as do the efforts "they" present to the marketplace. One would (well, *I* would!) think that there would be a greater motivation/pride in doing something "with your name on it" (vs. "it's just a job")...
Yes. And it is with that in mind that languages and tools evolve. The goal isn't to make the *best* programmers/engineers "more productive" but to make *all* more productive!
You've never sat in a room facing a customer (and his lawyer) and been asked: "Who's your backup?" The first time this happened to me I was so *completely* unprepared for it that I just sat there slack-jawed -- it had never occurred to me that I wouldn't be able to fulfill the contract (that's just a matter of *choice*, right?) The idea that I could get in a car wreck on the way home from THAT meeting just never entered into my calculus!
Thankfully, this was probably the most "mature"/established client I would ever encounter and he took it as an opportunity to show me the sorts of things he *should* (responsibly) be considering in any contractual arrangement.
But, if you had to archive (or MOVE) that project, would you know what to drag along with the sources to be sure you had taken all of the pertinent files/data/etc? E.g., I archive (small) projects onto CD's (ISO's) -- everything pertinent to the project: specs, parts lists, schematics, PCB layouts, source code, tools, etc. The CD/ISO acts as a handy "container" for everything.
In my case, I want to (or, in the past, have *had* to) distribute those sources to others. Having a convenient "container" is an asset. I don't have to worry about forgetting something. And, the recipient doesn't have to take special precautions to ensure they don't "lose a piece".
[E.g., in years past, I would deliver everything on magnetic tape (because floppies were way too small and writable CD's didn't exist). If a client misplaced one of the tapes... ]
Ideally, I would like the *source* to be the "container". But, that's just not practical -- embedding anything other than text in a source file would require some special preprocessor to extract the *code* from the rest of the "cruft" (e.g., tangle/weave).
But, I can, instead, embed the *code* in the "documentation"! Use the PDF as the container as it is relatively straightforward to extract the source from it (even *binaries*!).
HTML would be an option *if* you compile everything into a single file *and* ensure that the browsers that parse it will be capable of presenting each of the various types of objects contained within (e.g., photos, illustrations, charts, animations, sound clips, interactive demos, etc.)
There's no "perfect" solution so it falls on me to just
In many industries, there is a lot of overhead in getting a system ("solution"?) in place. Upgrading any portion of a toolchain may require a new "recertification/validation" effort: "How do we know that these tools, when "fed" the same sources that we know 'work predictably', will yield binaries that *also* 'work predictably'? I.e., how do we know that the tools don't alter the performance (correctness) of the final product?"
I've worked in industries where total sales volume could be counted on several *hands*. Do you want to have to reinvent the wheel for each unit you ship -- just because a tool vendor (or component vendor) decided to make a change?
This is one of the reasons I use so much FOSS, presently. If I come across a bug/problem that I *must* have fixed, I can either go looking for the problem myself. Or, parse the release notes of newer versions of the tool in the hope of finding a reference to the problem. Then, grep the sources for *that* particular portion of the "upgrade" and apply *JUST* that! I.e., instead of moving from version X to version Y (or even Z!), I can move to X.000000000001 knowing that *only* the behavior that I needed to have repaired had been altered -- no "risk" to any of the other code in my project!
A lot of the older architectures were much cleaner than modern processors. (Of course, there were some *dogs*, as well!) We looked into using T11's (or was it F11??) in a project many years ago. But the pricing was ridiculous (and it had to be an incredibly expensive device to produce!) I think there were
Of course, I understand that and I know this is the reason behind the rise of high level languages, obviously. But I think this puts a brake to the speed of overall technological development - chaining the fast ones down to the speed of the average ones. The fact that this is driven simply by those in control in order to make sure they retain their control does not help much accepting this reality, I have to say.
Oh I have had that from customers - only those who have been buying our products in order to try to copy them or by those who look for an excuse to give the order to someone who costs a few times more (and get their bribes). Typically I sell products, not services - and if I sell a service it will usually be a whole design of some one-off, hard enough to design thingie so it makes sense to get in touch with me (i.e. when they don't know if it is doable at all - and if I am lucky so they want something really doable :-) ). In the case of a product sale the backup for something which is in production is nothing they need to be concerned with, any literate person will be able to keep the production running. In the case of a unique design service sale they will not be overly concerned with "backup" either (I have such products which have been at work at labs for many years, outlived many of larger companies who would -falsely- claim to have "backup"), if they have come to me they will have explored the cheaper options beforehand.
So the only case where this is a valid consideration is in the consumer sector where someone wants to pay for a design and live on it doing small modifications for the next 30 years. I can argue my design would be good enough to need much less/easier modifications than a mainstream one but I am not sure this will come across well, I do not get many such inquiries anyway :-).
Don wrote: "The last comment is the kicker -- if you're coding for your eyes only, you can do things a lot different than if others will have to view, maintain or enhance your codebase"
Hi Don, I have followed your posts and I agree with your views on most things, but I have to go against you on this idea.
Unless your memory is significantly above average, this comment is just wrong. It is the opposite of this that I use as a guide to comments in the code. IOW,
what information will I need if I have to fix a problem in the code 6 months from now? That's what drives the comments.
If I would need that information, then I am sure another maintenance programmer will need it even more!
Trust me, my memory is *not* significantly above average! :> At this point in my career, I'm approaching the "Kelly Bundy" point (i.e., every new datum forces an old one *out*!)
OTOH, I don't need to leave notes to tell me how a binary search works! But, I *may* need a note to explain why I chose that search algorithm for *this* data set instead of another approach. That sort of detail is likely *not* evident "in the code" but, rather, "in the application".
I *don't*, for example, justify why I insert an invariant *here* in my code -- and not (another one) *there*. The fact that the first one exists and the second does not conveys information to me that will be lost to another set of eyes. But, at the same time, it doesn't rigidly *constrain* those other eyes -- effectively tying down implementation options unnecessarily.
[E.g., "at entry" and "at exit" invariants are bound by the function's contract. But, within the body, any additional invariants I install may be related to my *choice* of implementation and not "set in stone". OTOH, others may, in fact, be!]
But, then you're assuming another maintenance programmer will *start* with the same level of familiarity with the algorithm, purpose, etc. that *you* bring BACK to it.
E.g., any application-specific knowledge isn't likely to magically come with that new set of eyes. Nor are *you* guaranteed to remember it some time later -- even though it seems second-nature to you *now* (because of your overexposure to it).
Writing good/effective comments is tough because you want to avoid saying something "obvious" -- yet *ensure* you say everything that's
*necessary*. An *objective* judgement call is required of you despite your very *subjective* experience with the subject matter: "What would SOMEONE ELSE consider as 'necessary'?"
One of the most sickening feelings (to me) is looking at some of *my* code and wondering "why the hell is it written THIS way?" (i.e., when there are obviously *better* ways to have done it!).
E.g., in one of my speech synthesizers, templates are tabulated in RIGHT-TO-LEFT alphabetic order. So, "EX" comes *after* "UN" -- which, in turn, comes after "EXTRA"!! An entirely different piece of code searches these templates -- not the "normal" code (which searches left-to-right).
Someone (me?) encountering this later can see an obvious opportunity for refactoring and go about systematically "fixing" all of the templates and replacing the "special search code" with another invocation of the *normal* search code. And, when done, wonder why it doesn't work -- AT ALL!
[Or, sit there staring at the code wondering "why the hell is it written THIS way?"]
*Then*, studying what the original algorithm was ACTUALLY doing in order to uncover the reason behind this "odd" approach. After you've wasted effort "fixing" it!
A three sentence comment with example makes this crystal clear. At the same time, eliminating the need to comment the actual "search" function in *any* detail.
[OTOH, the choice of "naive/trivial" search algorithm may merit some explanation: "Why are you doing this so LAMELY when there are more effective ways of doing it?" Ans: look at the number of templates involved; what are you going to *save*? what will that *cost* you??]
As I've said, "software engineering" is really missing a tool/mechanism to more effectively "explain" what it is trying to do. Either a more expressive language (we've seen countless attempts at this and none seem to really hit the mark -- in an application-domain neutral way!) *or* a way of easily augmenting "code" with "description/explanation".
The question then becomes: what do you do while we're waiting for that "solution"?
They run those PDP-11's because the amount of regulatory approval and pain needed to change even the slightest part of a nuclear reactor installation would be much more expensive than keeping the 11's running until the reactor is decomissioned in 2050.
It is always a good idea to comment so that others can understand, and also so you can understand in the future. It is not a bad idea to assume others will have to understand, and write them with that assumption.
Even so, I can imagine using some tricks that I would remember and understand, but wouldn't want to try to explain in the comments so someone else could understand.
Maybe my memory is somewhat above average. I do still remember the first program I ever wrote (well, had help writing) when I was nine years old, and running it on a B5500.
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.