# Non-text format for source code

• posted

Anything these days without a youtube link is useless to todays youngsters :-)

........

They are always misused rarely properly used.

My view if marketing types want the thing to look the same as printed paper they should print it on paper, not on the infinite combinations of screen sizes and resolutions.

My personal bugbear is NEVER specify anything other than images on web pages in pixels, that is what point (pt) for height and em, el en used as widths are for oh hang on they come from printing terms... I wonder why 300+ year old technology definitions still work and the new ones dont.

--
Paul Carpenter          | paul@pcserviceselectronics.co.uk
PC Services 
• posted

Sorry all these fancy things like 'workspaces' and 'projects' on IDEs and the like assume that that software or that file is the WHOLE project and we can be LAZY. Documentation exists in many forms and from many sources, the process must allow for updating ALL associated documentation.

I have seen so many problems where people dont know what something is made to even for ASICs, I come to design the tester system and all the documentation contradicts itself from original to spec to final design.

Anything which has funky formatting suffers from

1/ inability to run diff 2/ Which doc or XML or other strange format and version of it 3/ Will the format always be backward compatible even in saving corrections 4/ Anything with links is great for a product lifespan of SIX months MAX a/ links to dataheets get pulled, reshuffled or company goes under b/ external links are always ephemaral c/ even links to your own docs are subject to i) Vagueries of drive mappings on networks ii) Most packages will insist on ABSOLUTE paths only to C:\My Documents\.... C:\Programme Files\Stupid IDE\Workspace\... d/ Use of fonts and colours is VERY system dependant what if that font is not loaded on that system or worst still no alternative scheme is given as people will always have Colibri on their system The colour scheme has been renamed 5/ The IDE that reads this file is no longer supported as the company who make it have gone bust, been bought out. 6/ No doubt the resulting document can only be read by that software on that system with that resolution of screen.

I have done a lot of work even with special document archives for museums and the like, and PDF Archive format will ONLY allow about FOUR fonts in it (Courier, Times [Mew Roman], Helvettica/Arial and one other).

Basically the code must always be readable, unless you really expect to write once and BIN it.

--
Paul Carpenter          | paul@pcserviceselectronics.co.uk
PC Services 
• posted

Yeah, that's what I do, as well. However, I happen to actually LIKE the idea of not having to force others (or me) to put their fingers into several applications at the same time just to understand ONE function. It would be nice to have an international source code standard that goes past ASCII, after all these years.

But yeah, I do what everyone else does and it works. I can just imagine something nicer. Sometimes, change doesn't occur unless you can imagine your goals.

Jon

• posted

I agree here! And it's one of the things I ask myself when writing comments in code.

But just to stay on my earlier point, it does add value sometimes to include a diagram inline with the function. In the past, where it was legible enough and useful enough, I've used ASCII drawings. But it is painful to do and the question of what value is added in an ASCII drawing is a slightly different question than it may be were it possible to use even the most basic drawing tools. I think having them available inline would modify at least _some_ of what I add and whether I add it. And in the end, I think it would improve, not injure, my own output. I can't speak for others, of course.

Jon

• posted

If you had a "compiler" that stripped away everything not immediately inside a ... block, and handed the code to gcc, then you could invoke your compiler from the makefile and all would be well, no?

Mel.

• posted

That's not the issue, though. It's a different concern.

There are a lot of things can do, and have done. What counts in part, though, are my customers and what the programmer skillsets and tools they will have access to ten years from now. I'd be looking for an internationally _supported_ standard here. Not ad-hoc stuff I cobble together.

I believe that my clients would benefit from a supported standard. I don't believe that they would benefit nearly as much from one-off tools I write. I've done a LOT of that many years ago. Problem is, I'm not in the business of supporting those things and I may not be accessible, either. And it adds to the support load, as well, if they have to adapt them to new operating system environments.

Anyway, nice try.

Jon

• posted

That's a process problem. If the team doesn't believe that comments and documentation matter, then you're doomed from the start. This is culture. The idea that then arises that there shouldn't be any comments or documentation because it'll probably be wrong.

See above.

Yes, that is a real problem with Doxygen, but the root cause is deep in C culture.

See above

IMHO the problem is more subtle. Code documentation is for the maintenance programmer, who is perceived by many as being dull. The original author is, of course, a genius who doesn't need comments. Those of us who find themselves maintaining code that they wrote 20+ years ago know that that the maintainer's job is just as hard as the author's. Those of us who can still read also know that the lifetime cost of software is probably three times the authoring cost also realise that indulging the maintenance programmers is a "good thing".

Stephen

--
Stephen Pelc, stephenXXX@mpeforth.com
MicroProcessor Engineering Ltd - More Real, Less Time 
• posted

The very word "comment" is deprecating and invites scattered, unorganized "commentary" rather than proper reasoned, organized rationale and description. It was a very unortunate choice of the programming pioneers, considering the role that "comments" should fill today.

If we are asked, of course we "know" that the "comments" in source-code should not be just comments, but should be something more. But I suspect that there is a bit of subconscious sub-estimation of their worth, because they are called comments.

To get back to the point of this thread, it seems to me that the idea of links from source code to documentation is a good one. In addition to the problems with diff and version control that others have mentioned, in-line documentation causes problems in high-integrity development, when any change to the source-code files triggers expensive retesting and other quality-assurance procedures. In principle, one can try to argue that changes to "comments" cannot change the executable code, but even if one proves that by comparing the old and new binaries, the source-line-to-code-address mapping will be screwed up, as will file time-stamps and versions. (Well, maybe the "non-ASCII" content would not count in the source-line numbering.)

For source-code with links to "non-ASCII" documents, someone skilled with Emacs Lisp (not I, therefore) could probably whip up at least the viewing/browsing functionality quickly, so that one could click a link in an Emacs source-code buffer, and bring up the linked document in a browser window on the side. Or even a word-processor, math program, or what have you.

I think a side-by-side view of source-code and documents is preferable to an in-line interleaving. In an in-line view, with the source-code and "non-ASCII" documentation sharing the same window, it could often happen that only a small part of the code of a function would be visible at once, which would make it difficult to understand the overall structure of the function. It seems to me that this problem is generic to "literate programming" schemes -- the prose part dilutes the formal code. Perhaps the problem could be reduced by an editor that could fold/unfold the non-ASCII stuff... but side-by-side feels better.

I would keep the linked documents in the source-code folders, close to the source files that link to the documents, so that the links can be short relative links. This should avoid the problem of links decaying with time.

--
Niklas Holsti
Tidorum Ltd 
• posted

Twenty years? I tip my hat to you, sir. I find myself looking at things I did *two* years ago and wondering just what the hell I was thinking. ("Who was the bloody fool... or, right.") When you're immersed in the problem and "in the zone," it all seems so obvious.

• posted

Agreed. And nicely said.

I guess the point we all agree on is that it's not just for others but for ourselves, too.

Jon

• posted

That sounds very much like my thought on the proposal. You define a "mark up" language that has a compiler that converts your documentation file into the source code for the target language (like C), and then have a rule for your makefile that runs that compiler as needed to extract the source code from the original file.

• posted

Haskell has a convention ("Literate Haskell") where the code is delimited by \begin{code} / \end{code}, allowing the source code to be a LaTeX document. There's no reason this convention would be limited to Haskell only.

Stefan

• posted

But that's not the fault of Doxygen. That's general developer sloppiness, and I don't think there's a cure for it.

I have worked with Literate Haskell source code. Remember, Literate Haskell is specifically designed to make writing documentation along with the code easy. The average source file contained a few section delimiters ("Type Definitions", "Private Functions"), and that's it. Therefore, it isn't any better than the average free or commercial software project that contains almost no comments other than the license header and the occasional diatribe how much sucks.

Stefan

• posted

And every time you find yourself about to write a comment stop and ask yourself

Why is the code so unclear that it needs a comment?

Can I re-write this code so that its obvious what's going on without a comment?

--
Grant
• posted

Almost certainly the most useless comment ever seen 8-)

My personal favorite: the original Unix sendmail was approximately

11,000 lines of C. The source contained exactly one comment pertaining to an initialized global. The comment read: "don't change this!"

And to keep out of these discussions. Obviously I lack that discipline 8-)

• posted

On 02/02/13 11:22, Stefan Reuther wrote: > Mel Wilson wrote: >> Jon Kirwan wrote: >>> Yeah, that's what I do, as well. However, I happen to >>> actually LIKE the idea of not having to force others (or me) >>> to put their fingers into several applications at the same >>> time just to understand ONE function. It would be nice to >>> have an international source code standard that goes past >>> ASCII, after all these years. >> >> If you had a "compiler" that stripped away everything not immediately inside >> a ... block, and handed the code to gcc, then you could invoke >> your compiler from the makefile and all would be well, no? > > Haskell has a convention ("Literate Haskell") where the code is > delimited by \begin{code} / \end{code}, allowing the source code to be a > LaTeX document. There's no reason this convention would be limited to > Haskell only. >

The concept is not limited to Haskell (though the details of implementation are different for different languages and tools):

However, systems like this are nothing more nor less than you can do with perfectly ordinary ASCII-based programming languages along with tools like doxygen (or javadoc, python docstrings, etc.). The only difference is that here you are in "documentation mode" by default and start "code mode" with some sort of delimiter - while with doxygen you are in "code mode" by default and start "documentation mode" by a specially formatted comment.

• posted

Good questions, of course.

But some functions DO require additional specialty information to show the mental pathway of getting from a well-trod mental space to some arcane dead-end. An example that springs immediately to mind from an old project is the idea estimating the tau of a radioactive decay curve by taking the log of the ADC data to linearize it, then applying a standard least square error fitting routine. Some of the summations drop out because the x(i) values go from 0 to 1 to

2 to... etc., and the ADC data has it's own constant factor associated with it. The number of data points also varied, though.

The resulting computation was performed in assembly code on an ADSP-2105 and ADSP-2111 processor using one ALU op and up to two data fetch ops per instruction. But the main point here is that the least square fitting algorithm had some specialty constants and a very specialized equation that no one would normally find anywhere else in the literature. Getting from the usual literature on the subject to the end point takes a fair amount of work. Since that work was already done, it helps to document it clearly. It's neither a LOT of documentation, though, nor is it trivial. It's in a perfect mid-sized placed where it's just the right bite size for inline documentation at the head of the module so that the source of the specific constant values used and the specific summations chosen are clearly derived and available.

I won't belabor the issue further, though. We can disagree about what should, or should not, be present in code. Suffice it that it is MY opinion that in this particular case and for the client I had, it would have been very appropriate to include. However, it would be vastly more complex to write in ASCII and confusing besides. There is no question of that in my mind, because I actually first attempted to do exactly that and then gave it up as excessive and obtuse and ugly. So I retreated to the usual method -- a separate document that had to be added to source control and monitored and then also added to the scoping documentation so that newcomers would be aware of it, as well.

Jon

• posted

n
d

Oh you can ask yourself that once and learn to live with the obvious "no" answer for the rest of your life allright.

Then get used to commenting your code well. In fact, how to comment code is something one has to learn the first year if not the first month when one begins to learn programming. Misleading people that comments can be unnecessary is one of the most counterproductive achievements of the high level languages last 2+ decades, its debilitating impact is to be carried with the industry for years if not decades - and who knows how much longer it will even stay as unnoticed as it is now.

Uncommented code is just garbage.

Dimiter

------------------------------------------------------ Dimiter Popoff Transgalactic Instruments

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

• posted

True enough. I guess I read his questions more as asking, "Is this specific comment appropriate and helpful?" and asking, "Can I improve the code to make it clearer?" Not to the exclusion of comments. But just to the overall improvement of the net result of code+comments. I hadn't read it to say that comments are to be eshewed. If he meant that, then I also disagree flatly.

Jon

• posted

David Brown wrote: [ ... ]

I was too elliptical. I was actually thinking about HTML as the markup lanugage. I just forgot to say so.

Mel.

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.