Parser, again!

Tutorials are helpful and have advantages that cannot easily be duplicated by other means, but they are not sufficient.

Decent comments describe the codes' requirements and guarantees whereas tutorials only show a few examples of usage.

Javadoc and the Java type system are imperfect, but they are awful (and aweful) lot better than the C++ "equivalents".

But then one of the impressive things about the 1996 Java Whitepaper was the way it stated "feature X has been shown to be good by language Y", and "X has been shown to complement Z in A" - in other words Gosling et al learned from a wide range of previous experience.

OTOH, the C++ world almost seemed to take a peverse satisfaction in not knowing what had been show to work fail - and thus they reinvented many elliptical wheels.

I once did a reasonable job in that respect only to find that the "invoke XP magic" weenies promptly made all getters and setters public (rather than protected) merely so that they could add trivial and futile unit tests. They completely and willfully missed that my pre-existing unit tests had already done those tests, and that by opening up the interface they enabled gross misuse of the library.

The concept of a small easily-maintainable public interface was beyond their comprehension. (We got the code so we can easily change it whenever any on e of us feels like it). Sigh.

I agree with you and it matches my experience, but I'll play devil's advocate...

It saves time for the /next/ project - but the project manager won't be the PM for that project. All the current PM cares about is getting /their/ project completed under budget.

Hence not commenting is a standard externality: somebody else's problem.

Many projects (mostly non-embedded, and often database projects) are mainly tedious boring CRUD stuff, i.e. create read update delete with just a tiny bit of business logic all executing in a poorly-understood magic framework execution environment. Comments don't add anything; it is just as easy to read the code.

For several decades I swore I would never have anything to do with databases. When I couldn't escape a project that was largely DB CRUD plus a little bit of GUI, I realised how wise my younger self was :)

In addition, I suspect the corporate politcking and in-fighting was so vicious partly because the tech was so boring!

[attrs elided]

Religion is great -- except when it isn't. :<

I've (historically) tended to be overly verbose with comments, identifiers, etc. Even "unrolling" idioms where they can be intimidating (folks seem to think that if they can use less characters to express an operation, the compiler will use less *code* to implement it!)

In my early products (1970's), it was almost a 1:1 ratio of code to comments. Easy with the short "line lengths" that ASM afforded -- just tag a comment over on the right side of the page and let it continue over the N consecutive lines to which it applies: ;advance the pointer to the... ;...next goal in sequence and... ; ... recurse

This, however, gets impractical with longer line lengths common if HLL's (longer identifiers, too!). So, I started moving to "preambles" (prefaces?) that would introduce the code fragment/paragraph that follows. Or, a one-liner above a particular "significant statement".

In my most recent projects, I am moving most of the commentary

*out* of the codebase entirely (I played with LP and found it "tedious", to say the least!). In separately maintained documents, I can express what I want to say without the constraints of AN IMPLEMENTATION binding my explanation. I can develop an idea from scratch, illustrating "naive" approaches, refining them, pointing out pathological cases, etc.

And, I am not constrained to the exclusive use of text! An illustration is often *so* much more instructive! Or, a graph that makes clear how one thing relies on another. Or, a sound clip (how do you describe the difference between a "Boston" accent and a "New York" accent to someone who has heard neither?)

I'm currently working on embedding interactive examples in these documents so a "reader" can experiment with the issues being addressed and "see" the results firsthand (instead of trying to tabulate umpteen different cases: how does glottal open percentage contribute to "breathiness" in speech?)

Because this document is NOT intimately tied to the codebase (i.e., "this paragraph of commentary belongs with this fragment of code..."), it can survive drastic code revisions untouched.

And, from the software's perspective, it eliminates the need for lengthy explanations of what you're doing at any particular point in the code -- you can make an offhand reference to something from the external "overview"/tutorial document without having to spend lots f verbiage explaning it, IN the code!

No, hell is having to make other peoples' code *work*!

And the person doing the commenting has the sense to know

*what* to comment (i.e., what's the *real* essence of this operation, not just the "obvious details")

I've actually taken this approach at the application level. Return identifiers that let the user see what part of the documentation is appropriate to the problem at hand! (instead of "error 0x80043584")

Now that's becoming religion (see comments above :) )

There is always a need for some documentation outside the codebase.

However I have found, with Java in telecom and financial soft-realtime systems, that this is an /irreplacable/ 90% solution: - carefully separation between - "client" API: public _interface_ at the top-level that containing all that is used by clients; typically a list of methods interface and a factory class - "implementation" API: internal _abstract_classes_ that provide the framework for the implementation - "extension" API: _protected_ internal classes/methods so that subclasses can override/extend - "internal" API: _private_ classes/methods except where necessary to widen visibility for the client/implementation/extension APIs - liberal careful use of the _package_ namespace mechanism to enforce the above - use of Javadoc, a neat mechanism for entwining and separating the code, comments and documentation - use of a IDE with code completion, which naturally presents a client with /all and only/ the methods that can be invoked at each point

Little of that is possible in C. C++ is a little better, but a pale echo of the Java mechanisms which is usually avoided because it is so easy.

In my experience diagrams are principally useful at a much "higher" documentation level than code.

With Java the promise of UML has largely (but not completely) been made moot by modern refactoring IDEs. C/C++ fundamental ideals preclude such refactoring browsers.

Interesting at the design level, but I'm skeptical about the code level.

That's the function of my "client" and "extension" APIs documentation.

In Java, that's all part of the Javadoc combined/extracted with/from the code.

Oh yes. Good taste and intelligence. Silly of me to forget that it helps to have competent employees :(

Hasn't everybody been doing that for the last 15 years?

In Java to a significant extent that happens naturally when an exception is caught and handled. Simply give the exception a decent name and toString() method.

Hmmm, on that one the devil seems to be doing so-so I guess. I have very little if any experience with product managers to be able to judge but I imagine that even a PM has to rely on the same person for more than a single project at times. So he might also get the "next" project delayed... :-) .

Ah, on that the devil is doing quite well I think. I write very few comments in command scripts for example (usually a header explaining how to use the script). A comment line here and there inside, may be. And the script language is (well, has become over the years) not all that easy to read (variable names which can be made up of variables, partial variable extraction etc.). But my scripts tend to be what, tens of lines, a few hundred at most (if I ever wrote one that long, not so sure; over 100 yes, over 200-300 - don't know).

Another gray area are my comments within macros. Write none and it may become hard to understand (in VPA I rely a lot on a very powerful system of macros, recursive, script processable, partial argument references etc. etc.). Write a comment inside and get it repeated too many times - and likely out of context as it comments the design of the macro and not its use... :D (this applies only if I need a list to look at how the macro is proceeding).

:D Don't really know (no recent direct experience) but I can well imagine this is the case. I know I hate to the point of getting like hysteric when I have to do the same thing more than once at times (typically because something won't work as expected). I am not sure if I would take another option at such a moment if I had it, I might well do. Then again I might not, my stubbornness would likely kick me back to do it again after all :D.

Dimiter

------------------------------------------------------ Dimiter Popoff, TGI

------------------------------------------------------

Sounds like I wouldn't want to look (let alone maintain) that code!

Macros and templates in most (all?) languages appear to be a point of irritation to extent that they become painful.

I try to avoid them for all but very low-level bit twiddling.

There's the literary problem too: different readers will have different needs, so it would help to know in advance whom the comment is for. In a perfect world, a comment would completely explain the next bug. In this world: "Yeah, right."

Mel.

No. It's not "enforced". Rather, it's just the most convenient, maintainable way of presenting a *lot* of background information to the developer in a way that doesn't clutter up the sources needlessly.

First time I did this was for a 9-track tape driver that I wrote. Pages and pages of commentary explaining how the interface(s), formatter(s) and transport(s) interacted. This was necessary so a maintainer would understand why *this* path was optimized a particular way while this other (seemingly equivalent) path was not. Also, essential for someone to understand how the seek algorithms worked, how "read backwards" was a viable operation, etc.

Putting all that *in* the driver "code" made it unwieldy. And, it didn't *need* to be there -- as long as the person reading/maintaining the code could be relied upon to be familiar with its contents!

This made commenting the *actual* code much easier -- I could just concentrate on decribing *what* it was doing instead of *why*.

In theory, *specifications*. In practice, I rarely encounter any "live" comments outside of the actual code itself.

I think commentary is largely a function of the mindset of the coder. I like leaving notes to myself. Hopefully, they have value to others, as well. Often, they are reminders of boundary conditions or dark corners that could bite me. Other times, reminders of assumptions that are *not* valid (e.g., I posted a program in S.E.D recently that had a common subexpression intentionally factored out of the statements in which it should, otherwise, have been comfortable residing -- let the compiler find it and factor it out, right? Ah, but compiler would NOT do that, in this case so do it manually...

I find most of the documentation that is "eeded" in the code explains the algorithms being used and their "gotchas". Most folks -- given an explanation of the algorithm -- can usually follow along *lightly* commented code quite well. The real chore comes when they are trying to understand your algorithm, any special cases that you're handling, etc. This, IMO, doesn;'t need to sit *in* the code as long as you can refer back to something in the "external" documentation that will "ring a bell" with someone who has, presumably, read it.

As I saaid, its helpful in illustrating the underlying basis for an algorithm. E.g., taking the breathiness example, you play with some parameters and *hear* the difference in (otherwise constant) speech and its a lot easier to relate that effort IN THE CODE to the audible result. You have a first-hand feel for what the parameter does and it's "value" in the algorithm. And, an easy reference against which to test an implementation! (What is 40% supposed to sound like? Is there really much difference between that and 37.5%? Can I eliminate a floating point multiply if I restrict the range of settings...?)

But they are still tied to a particular API. What if the API changes?

E.g., one can implement "breathiness" (above example) in any number of different ways and the description of its role as well as the interactive demos remains unchanged (aassuming the code gets implemented correctly).

748236957>>>> smell and provided time is allotted for comments.

IMO, that's far more important than any "religion". If people look on comments as a "chore", they may as well not write any!

Shirley you jest? :>

I take it a step further -- it's a reference *into* the on-line manual. So, you can have a verbose description of "how you got there" and how you can *fix* whatever your "problem" appears to be.

Hah, well, I thought it would sound like that. But it is not. Generally I think of writing scripts and other very high level sort of thing not as of "programming" (which is of course wrong but this is how I feel about it). If you know the script language you would have little if any problems reading a small uncommented script of these though. Here is a brief example I did just recently (executed by the dps ftp client upon start so it will have its own scratch directory, thus being able to run scripts which use temporary files of the same name concurrently in multiple instances):

• @eoff @path \syslib\scripts\ @path \syslib\utility\ @path \syslib\commands\ @task @setl ftpno ]i@0 @setl temp [shellwd @setl ftpwd ]temp ftp{$]ftpno } @ifdefl shellwd setl ftpwd ]shellwd ftp{$]ftpno } @mask @run md ]ftpwd >#null\ftp{$]ftpno } >

I've seen too many people not realise that they are in the process of falling into that trap (and in some cases, not realise it when they were in it!).

And that's the problem with /all/ "little languages", whether they are interpreted, compiled, expressed in XML or ASCII.

Worst example I've seen? if (FOO) { ... } where FOO was defined elsewhere and macro-expanded using /many/ levels of macros before being compiled. And such if-then-else statements were nested up to

10 (!) levels deep.

Why have FOO as a macro? "The source code is kept in a repository, but FOO is not code and is changed by on-site installation engineers." I never succeeded in getting them to even understand that FOO was actually part of the source code, let alone anything useful.

The "little language" issue is , of course, soluble if the creator is also the only maintainer.

I have no reason to doubt it. Has anyone else had to modify the code?

Which is the other problem with "little languages" - you can't leverage the stunning analysis/creation tools available for mainstream languages and environments.

I've seen a project spend several man-years creating an SDL-to-C tool, only to have potential customers reject it because nobody was prepared to maintain the toolchain. IMHO that rejection was a very reasonable decision!

I think I have witnessed that, too. But I can't say I have fallen into the trap, not during last 2+ decades at least. Except the "feeling" this is not real programming I also have a good idea when I write something I might use again one day and when - not. Most of time things are to be reused so I do things in a reusable way (not always consciously). But there are times - e.g. writing a script named "test" which is to do some highly specific operations to allow me to debug something etc. (and usually gets deleted shortly).

Well of course, I have accepted that at the very start of the whole now nearly 20 year old DPS effort. I think under the score my work has benefited - I could not have been half as productive had I relied on software not under my control (and not having to maintain the entire house in working order which in turn has kept me in good shape, the last perhaps more important than it sounds).

This matches my observations (not many) on how people misuse macros. Macros should be used only if not using one would be impractical. It is hard to give a recipe of course, a macro may be "practical" and be anywhere between 2 and 2k lines.... :D . One example of "good" macro usage I have is when I needed to assemble some old 68HC11 code; I just implemented the hc11 assembler using macros in A32 (my 68k predecessor of vpa, produces cpu32 code). Took a whole day IIRC. Another, somewhat harder to do example was implementing the instruction set of a smart DMA controller (that on the mpc5200B). In the latter case I had to invent also some mnemonics I think, it took more than a day since I was

100% unfamiliar with the DMA and had to understand it etc. during the process. But it was very "enabling" overall :D .

That has been the underlying assumption when I started it all these years ago (I started DPS using 68k assembler in 1994 and did the vpa thing about 10-12 years ago when I migrated the code to PPC (now (again) power...)) . But I suspect any programming language has started if not under the same assumption at least in a similar way.

Not really. I did have a customer who wrote his own scripts without any prior DPS experience though. Most other customers expect "customer support" if something like that is needed though :D .

Dimiter (somewhat surprised to discover being distracted by the expectation of a football game which starts after an hour... have I really become a real Arsenal supporter? :D :D )

------------------------------------------------------ Dimiter Popoff, TGI

------------------------------------------------------