Maker Pro
Maker Pro

another bizarre architecture

V

Vladimir Vassilevsky

John Larkin wrote:

Strange. Some people have a powerful vested interest in the premise
that good programming is impossible.

It is not impossible. It is just not worthy in many cases.

Vladimir Vassilevsky

DSP and Mixed Signal Design Consultant

http://www.abvolt.com
 
P

Paul Keinanen

But it's seldom the CPU or the memory that fails;

Hardware will fail quite often due to radiation, EMC problems, UPS
failure or simply capacitor "rot".
it's the software itself.

I try to write my software so that it wont't fail until I am retired.
Memories don't leak, but memory allocators/deallocators do.

You have memory leak problems only if you use deallocators :).

A program can use allocators at startup, but should avoid them during
the next decades the program is running.

Paul
 
J

John Larkin


So clean, safe, documented, bug-free code is routinely produced when
it matters. But a premise is that the people who create the code first
have to believe that clean, bug-free code is possible, and then they
have to pragmatically adopt the engineering disciplines needed to make
it so.

It helps if they have never studied CS, and that jet engines are not
abstractions to them.

John
 
R

Robert Adsett

I agree that more comments helps.
But in spite of that, a deeper knowledge of the various interconnects
is required, that cannot be put even in several pages of text (and who
would read these).

Before interactions get that complex I'm usually questioning the
approach. If the interconnects are that complex they really do need to
be documented.

However, that didn't even approach being an issue in the given example.
It could have been raised to adequate commenting level with only a few
comments (2 or 3 lines). Something to indicate what the function was
supposed to do, some to document arguments/return and maybe a quick line
outlining the main loop.

As I said the other example I looked at from the same page was even
worse, even the file header was completely wrong. This should just be
basic code hygiene. John's original comments were correct and the
response that he should just learn C was off the mark. The issue wan't
a language issue but inadequate commenting. The original routine he was
pointed to was quite straightforward, not a lot in the way of
interconnects requiring a lot of 'deeper knowledge', but the commenting
practice appears to extend beyond it, consistent with the view that if
you don't handle the simple cases properly it's unlikely the more
complex ones will be handled correctly. It's basic discipline.

Robert
 
J

jasen

If your vc system tells you that two subroutine sources differ, what
do you do?
It certainly can't tell you *why* they differ, or how they
might behave differently. For that, you must either read the comments
and revision notes (lots of luck finding them!)

typically they will be in the charge of the revision control system
or compare the code
character-by-character and try to figure out what's going on.

there's a program called diff that compares text files and points out
differences..., it's great for this sort of stuff.
Or just
use the latest one, on the assumption that any bugs aren't your fault.

Now, what do you do when 12 versions differ?

you read the changelog.

Noone should modify a libgary function in a way that reduces it's
capability.
Adding sign checks to the resistor function would be a bad thing, -
suppose you were using it elsewhere on an inverting transconductance
stage,,,


Bye.
Jasen
 
M

Michael A. Terrell

Jim said:
Hey, John Larkin! How come you keep attracting the nutcases ?:)

...Jim Thompson


I think Homer is calling in all of his friends to show their idiocy,
in an attempt to lower the standards. :(


--
Service to my country? Been there, Done that, and I've got my DD214 to
prove it.
Member of DAV #85.

Michael A. Terrell
Central Florida
 
J

Jan Panteltje

There is no need to use those continuation lines, which just
distort your code. A '\n' is just another whitespace char. to a C
compiler. In addition strings separated by only whitespace are
automatically concatenated. You can be much clearer with:

There is a problem with that, in case of text, consider this on gcc3.3:

Try this,
#include <stdio.h>

main()
{
fprintf(stderr,
"Hello\n
World\n");
}

grml: ~ # set-gcc-2.95
Reading specs from /usr/lib/gcc-lib/i486-linux-gnu/2.95.4/specs
gcc version 2.95.4 20011002 (Debian prerelease)
grml: ~ # gcc -o test4 test4.c
grml: ~ # ./test4
Hello

World
grml: ~ #

That compiles and works as expected.

But now with gcc-4.0:
grml: ~ # set-gcc-4.0
Using built-in specs.
Target: i486-linux-gnu
Configured with: ../src/configure -v --enable-languages=c,c++,java,f95,objc,ada,treelang --prefix=/usr --enable-shared --with-system-zlib --libexecdir=/usr/lib --without-included-gettext --enable-threads=posix --enable-nls --program-suffix=-4.0 --enable-__cxa_atexit --enable-clocale=gnu --enable-libstdcxx-debug --enable-java-awt=gtk-default --enable-gtk-cairo --with-java-home=/usr/lib/jvm/java-1.4.2-gcj-4.0-1.4.2.0/jre --enable-mpfr --disable-werror --with-tune=i686 --enable-checking=release i486-linux-gnu
Thread model: posix
gcc version 4.0.3 20060104 (prerelease) (Debian 4.0.2-6)
grml: ~ # gcc -o test4 test4.c
test4.c: In function 'main':
test4.c:8: error: missing terminating " character
test4.c:9: error: stray '\' in program
test4.c:9: error: 'World' undeclared (first use in this function)
test4.c:9: error: (Each undeclared identifier is reported only once
test4.c:9: error: for each function it appears in.)
test4.c:9: error: syntax error before 'n'
test4.c:9: error: missing terminating " character

Have fun.

BOOL calculate_current(double resistance, double voltage, double
*current)
{
if (debug) {
fprintf(stderr, "calculate_current: %f %f\n",
resistance, voltage);
}
if (resistance < 0.0) {
fprintf(stderr, "My-Program: calculate_current():\n"
"Your resistance is negative (%.2f),"
" you must be kidding right? Aborting.\n",\
resistance);
return SUCKS;
}
else /* whatever */;
}


That is true, about the '\'.

Note how I try to associate a format specifier with the appropriate
object. By the way, negative resistance normally implies an
amplifier.

What is not so good here, is that you use an if-else after an error return.
The normal program flow is to eliminate all special conditions,
and then end up with a usable case:


if(this_wrong) return ERROR_THIS;
if(that_wrong) return ERROR_THAT;
if(disaster)
{
eject();
exit;
}
do_your_thing
return OK

No need for if-else, and always the fastest way out, (as one would (hopefully) do in asm too).

In fact if-else, and especially 'else' is a very very dangerous statement, as else includes
all other cases!

:)
 
J

Jan Panteltje

["Followup-To:" header set to sci.electronics.design.]
On a sunny day (Thu, 01 Feb 2007 21:24:37 GMT) it happened Vladimir
<[email protected]>:

FILE *fptr;

fptr = fopen("filename", "r");

fread( fptr...)
BANG if file did not exist!

It's easy to post bad code, how would you fix it?

You check the return value and look at errno.
Read the rest of the thread (and libc.info, but I know you did read that).

seriously, checking for equal to zero is pointless,

It is not so pointless if that makes the rest of your processing not needed.
I did refer him to sci.physics for super conductor ;-).

The number could be so close to zero that it would have pracctically the
same result as dividing by zero (the only difference is you get "infinite"
as a result instead of "not a number")

double d = 1.2 - 0.4 - 0.4 - 0.4;

d is a small number, but, quite possibly, not 0.

Tell that my math teacher ;-)
 
C

CBFalconer

Jan said:
There is a problem with that, in case of text, consider this on gcc3.3:

Try this,
#include <stdio.h>

main()
{
fprintf(stderr,
"Hello\n
World\n");
}

You have failed to supply the closing quotes, i.e.:

fprintf(stderr, "Hello\n"
"World\n");

Please snip useless portions. The practice of topposting something
that has a selected quote is ridiculous. Snip the irrelevant
portions of the quote.

--
<http://www.cs.auckland.ac.nz/~pgut001/pubs/vista_cost.txt>

"A man who is right every time is not likely to do very much."
-- Francis Crick, co-discover of DNA
"There is nothing more amazing than stupidity in action."
-- Thomas Matthews
 
J

Jan Panteltje

Before interactions get that complex I'm usually questioning the
approach. If the interconnects are that complex they really do need to
be documented.

However, that didn't even approach being an issue in the given example.
It could have been raised to adequate commenting level with only a few
comments (2 or 3 lines). Something to indicate what the function was
supposed to do, some to document arguments/return and maybe a quick line
outlining the main loop.

As I said the other example I looked at from the same page was even
worse, even the file header was completely wrong. This should just be
basic code hygiene. John's original comments were correct and the
response that he should just learn C was off the mark. The issue wan't
a language issue but inadequate commenting. The original routine he was
pointed to was quite straightforward, not a lot in the way of
interconnects requiring a lot of 'deeper knowledge', but the commenting
practice appears to extend beyond it, consistent with the view that if
you don't handle the simple cases properly it's unlikely the more
complex ones will be handled correctly. It's basic discipline.

Robert

No, the code rules (always) because that is what the processor ultimately
executes.
Up until this day at least, processors do not read books.
So, many funny comments have been written, and sometimes not releated to what
a function does at all.
I understand and appreciate your post, but in the simple example that John gave
the C code says it all, at least for me, so I even skip the comments.
In the other case, your argument about complexity, lets stay with the newsreader
for example, and now I will have to do some source digging, here is how that
goes on for about 50000 lines(just counted these),

Code extract:
------------------------
/* extract attachment name from info file (first field) */
sscanf(temp, "%s %s", attachment_name, content_type_and_subtype);

/* NOTE: to use header content_type un comment the next line */
/* strcpy(content_type_and_subtype, header_content_type);*/


/* NOTE already done here, if helper fails, we can still erase */
/*
set the encoding variable, so that next time a double click
is done in the article_list_browser the attachment is launched
*/
set_article_encoding(group, article_id, ATTACHMENT_PRESENT, 1);

/* save the name of the attachment, so we can erase it later if needed */
set_article_attachment(group, article_id, attachment_name);

/* extract the content_subtype */
-----------------------

So, I am not shy with comments :)
(as anybody who reads my postings will likely have figured out by now).
Point is, the complexities that arise if some user does something somewhere in
the GUI, or data comes in, or what not, to keep everything working right,
without data damage etc.
This gets more complicated the bigger a program becomes, but not impossible
to handle.
NewsFleX with >50000 lines of code is on the verge of what I like to maintain.
It is still rock solid, but can be crashed by screwed headers and articles.
I could fix that, but once a year or once every 3 years and a 2 second restart,
is not worth spending a month time for.
Also, as you can se, all functions say what they do to the maximum extend, else
I could not read it (the code) myself).

Alos I wrote a CP/M clone in the ninety eighties without a single comment
in Z80 asm, and only numbers for labels, and it is not hard to follow if you know
z80 asm, only kept a list on paper to prevent double numbers for the labels.
And a list of variables and what they did.
So, and I wrote the whole thing in a 3 week holiday, so too much blah blah
about comments is also crap.
Learn C, or ASM, and be done with it.
LOL
Hell, I have reverse engineered many micros :)
 
J

Jan Panteltje

Don't care. This is a task for juniors.


I don't share the views of linux opensource gnu maniacs.


A lousy C programmer is teaching me.

Oh really, well and you insult open source programmers too,
maybe because you steal their code and use in your close sources projects?
WTF should I bother with somebody who does not check return values,
or refuses to learn about the C library.
 
J

Jan Panteltje

Hardware will fail quite often due to radiation, EMC problems, UPS
failure or simply capacitor "rot".


I try to write my software so that it wont't fail until I am retired.


You have memory leak problems only if you use deallocators :).

A program can use allocators at startup, but should avoid them during
the next decades the program is running.

Paul

That may be really difficult if you want to process video or images for example.
(User opens a bigger jpeg for example).
 
J

Jan Panteltje

So clean, safe, documented, bug-free code is routinely produced when
it matters. But a premise is that the people who create the code first
have to believe that clean, bug-free code is possible, and then they
have to pragmatically adopt the engineering disciplines needed to make
it so.

It helps if they have never studied CS, and that jet engines are not
abstractions to them.

John

I can agree with that, but it gives me that sales people feeling.
There was the NASA PC soft for the mars rovers, it was written in Java IIRC,
and it had a 3D verison for on the PC for Linux.
I installed it, and it 1) did not install (path was wrong and hardcoded IIRC),
2) got stuck after fixing that.
I realized something that moment I looked at that code, and I made the statement in sci.astro,
that if the same people programmed the_real_ rover, then it would be in serious problems.
Of course it _WAS_ in serious problems when its directory structure filled up
with too many files a week later.... (IIRC).
They fixed it remotely (relief).
I can feel that signature of disaster programming from just a quick look it seems.

So, if you can do it, very good.
But some still have a learning curve to take.
 
J

Jan Panteltje

You have failed to supply the closing quotes, i.e.:

fprintf(stderr, "Hello\n"
"World\n");

Please snip useless portions. The practice of topposting something
that has a selected quote is ridiculous. Snip the irrelevant
portions of the quote.

Take your pills
 
J

John Larkin

No, the code rules (always) because that is what the processor ultimately
executes.
Up until this day at least, processors do not read books.
So, many funny comments have been written, and sometimes not releated to what
a function does at all.
I understand and appreciate your post, but in the simple example that John gave
the C code says it all, at least for me, so I even skip the comments.
In the other case, your argument about complexity, lets stay with the newsreader
for example, and now I will have to do some source digging, here is how that
goes on for about 50000 lines(just counted these),

Code extract:
------------------------
/* extract attachment name from info file (first field) */
sscanf(temp, "%s %s", attachment_name, content_type_and_subtype);

/* NOTE: to use header content_type un comment the next line */
/* strcpy(content_type_and_subtype, header_content_type);*/


/* NOTE already done here, if helper fails, we can still erase */
/*
set the encoding variable, so that next time a double click
is done in the article_list_browser the attachment is launched
*/
set_article_encoding(group, article_id, ATTACHMENT_PRESENT, 1);

/* save the name of the attachment, so we can erase it later if needed */
set_article_attachment(group, article_id, attachment_name);

/* extract the content_subtype */
-----------------------

So, I am not shy with comments :)
(as anybody who reads my postings will likely have figured out by now).
Point is, the complexities that arise if some user does something somewhere in
the GUI, or data comes in, or what not, to keep everything working right,
without data damage etc.
This gets more complicated the bigger a program becomes, but not impossible
to handle.
NewsFleX with >50000 lines of code is on the verge of what I like to maintain.
It is still rock solid, but can be crashed by screwed headers and articles.
I could fix that, but once a year or once every 3 years and a 2 second restart,
is not worth spending a month time for.
Also, as you can se, all functions say what they do to the maximum extend, else
I could not read it (the code) myself).

Alos I wrote a CP/M clone in the ninety eighties without a single comment
in Z80 asm, and only numbers for labels, and it is not hard to follow if you know
z80 asm, only kept a list on paper to prevent double numbers for the labels.
And a list of variables and what they did.
So, and I wrote the whole thing in a 3 week holiday, so too much blah blah
about comments is also crap.
Learn C, or ASM, and be done with it.
LOL
Hell, I have reverse engineered many micros :)


This is a snip from an embedded product program, a combination
thermocouple temperature controller and NMR gradient driver. This is a
sort of printf function.

The program was done in a couple of weeks calendar time, released as
rev A, and has been in production for about a year. There are no bugs.
A bit over 4K lines of assembly. It's an absolute, monolithic assembly
of a single source file, no libs, includes, or linkers involved.

The .SBTTL directive create an entry in the listing's table of
contents.




.SBTTL . MAKE A FORMATTED ASCII NUMERIC STRING.

; THIS IS A NON-REENTRANT VERSION, WHEREIN WE BUILD THE
; DESIRED STRING IN THE 'J0..J7' BUFFER AREA. ON ENTRY...
;
; D5 CONTAINS UNSIGNED, RANGE-CHECKED 32-BIT VALUE
; JM HOLDS SIGN CHARACTER, USER'S OPTION
; D4 CONTAINS 'FORMAT' IN RANGE 0...5: THIS IS HOW MANY
; DIGITS APPEAR TO THE RIGHT OF THE DECIMAL.
; A3 IS POINTER TO 8-BYTE OUTPUT STRING
;
; 12345 FORMAT 0 IS ' 12345'
; -98765 FORMAT 3 IS ' -98.765'


BASS: MOVEA.W # J7+1, A5 ; AIM AT *END* OF STRING
MOVE.L D5, D0 ; COPY OUR NUMERIC INPUT
MOVE.B # " ", J0.W ; POKE A NECESSARY SPACE
MOVE.L # 10, D1 ; AND NAME A POPULAR RADIX

BOSS: DIVR32 D1, D0 ; DIVIDE BY 10, REMAINDER IN
D2
ADDI.W # "0", D2 ; MAKE THAT ASCII 0..9
MOVE.B D2, -(A5) ; POKE INTO 'J' STRING
CMPA.W # J1, A5 ; DID WE JUST DO THE 'J1'
BYTE?
BLS.S ZAPP ; IF SO, JUST CLEAN UP.
SUBQ.W # 1, D4 ; CHECK THE 'FORMAT' COUNT...
BNE.S BOSS ; IF IT'S THE APPROPRIATE
PLACE,
MOVE.B # ".", -(A5) ; POKE IN A DECIMAL POINT.
BRA.S BOSS

; NOW DO LEADING ZERO SUPRESSION AND MOVE THE SIGN...
; IF THE CALLER'S SIGN BYTE IS NULL, WE IGNORE IT.

ZAPP: MOVEA.W # J1, A0 ; AIM AT 2ND CHAR SLOT

Z10: CMPI.B # "0", (A0) ; DO WE HAVE A ZERO?
BNE.S ZEPP ; NO, BREAK OUT OF LOOP
CMPI.B # "0", 1(A0) ; CHECK THE *NEXT* CHAR...
BLT.S ZEPP ; IS IT A NUMERIC?
; IF SO,
ZOOT: MOVE.B # " ", (A0)+ ; SQUASH THAT '0' CHARACTER
BRA.S Z10 ; HOP POINTER, AND LOOP.

ZEPP: MOVE.B JM.W, D0 ; PICK UP SIGN CHARACTER
BEQ.S ZONE ; (IGNORE IF NULL)
MOVE.B D0, -1(A0) ; OK, INSTALL THE SIGN CHAR.
ZONE: MOVEA.W # J0, A2 ; AIM AT OUT OUTPUT STRING
; SHARE STRING MASHER BELOW:


.SBTTL . STRING MASHER

; MASH THE 8-CHARACTER STRING @ A2

SMASH: MOVEM.W A2 A3, -(SP) ; SAVE VALUABLE POINTERS

MOVEQ.L # 8-1, D7 ; PREPARE TO COPY THE 8-BYTE

SMACK: MOVE.B (A2)+, (A3)+ ; STRING FROM @A2 (SOURCE
POINTER)
DBF D7, SMACK ; TO @A3 (ASCII TABLE
POINTER)

MOVEM.W (SP)+, A2 A3 ; RESTORE REGGIES

RTS
 
P

PeteS

It's pretty rare that a chip has a bug that is not documented, as
opposed to a faulty device. Certainly someone has to find unintended
features of ICs, but more often than not it is the manufacturer,
although Joerg had some frustrating times with a TI LDO.
That said, I review all the documents for a chip thoroughly, just as
John notes below, including any errata. My datasheet error rate (finding
incorrect or even missing information in a datasheet) is pretty high;
probably about 1 in 5 data sheets. I would prefer the information to be
missing to being wrong - I know a number of people who have been bitten
by such things. I then talk to the manufacturer to get the right answer;
refusal to accept/fix an error in the datasheet is grounds to ditch the
part.


First, I read the datasheet and appnotes carefully for any hint of
gotchas. If we're doing anything unusual or risky or sole-sourced, we
test a few actual parts as well. If a part/mfr is deemed acceptable,
we enter that mfr and his part number into our materials database as
acceptable for purchase to satisfy out in-house part number. We know
which assemblies use each part, and can control it if, for example,
only an OnSemi part should be used on a particular assembly.

I (and probably any designer of reasonable experience) use that same
discipline. Software guys'n'gals might not understand the shudders the
words 'single-source' and 'allocation' cause to a hardware designer.
And engineers around here *only* design with approved parts. To create
a new library/inventory part, they have to get approval from the parts
czar, who happens just now to be me.

It's a good thing to have an anal-retentive parts czar for a lot of
reasons. The two primary ones (my view, YMMVG) are a part I am already
using is known to operate within a spec (which may or may not be the
datasheet, but it's the devil I know) and using the same part gives me
economies of scale, quite apart from the administrative and engineering
cost of adding a part, new schematic part, new symbol (all of which must
be checked of course), footprint etc.

Again, (for Jan's benefit) this is a discipline that hardware designers
live with daily.
*PLUS* schematics and pcb layouts are group reviewed before release.
Amen.


How many people have other people read their code?

Well, code reviews can happen, but in general (as with all
generalisations, it's not necessarily true of any one person) software
types tend to be more defensive about their designs that hardware. I've
been in design reviews where asbestos underwear might have been a
reasonable clothing choice, but all the comments were criticism of the
design and methodology, not the person. I've also noticed this tends to
afflict pure HDL people as well (as opposed to a board designer who also
does HDL). Obviously, YMMVG.

With a defensive posture, the review breaks down long before any
reasonable work could be done. I've let hardware designers go because
they couldn't separate criticism of a design from criticism of
themselves as people, and therefore simply argued because they felt
insulted rather than argue the technical merit of their approach.
Well, we test things pretty hard. If a bug does turn up, we find out
why and document the facts, and the actions to be taken, in an ECO. We
know the configuration of *every single* product in the field, and
notify users if the bug affects them.

I've done a huge amount of code to test hardware, and it is (imo)
perhaps the toughest code I had to write. It has to trap all possible
errors (and report unusual events I had not foreseen) without crashing /
unloading the driver / other side effects; indeed the test code has to
be so robust it keeps on running even in the event of a critical failure
of the test item *so I can know what failed*.

Typical production code just bombs out with 'failed' - like that's
really a lot of information. At one place we had a some compact PCI
boards we designed and I rewrote the drivers so they wouldn't just stop
on encountering an error; they instead maintained a status word that
could be queried so I would know that *if* the driver encountered
problems it could let me know what the problem was. That code was
ultimately found to be quite useful and ended up in the shipping product.
It's no illusion that professional hardware design consistantly
produces solid products and that professional software design often
produces bloated, buggy crap. As I said, I use hardware disclipines to
produce code, and that code inherits the simplicity and reliability of
the discipline.

Perhaps discipline is the key; software can simply edit and rebuild, but
a hardware change is not quite as simple. For that reasons we have to
strive all the time to 'get it right the first time', a discipline some
in software see as not applicable (perhaps with some justification,
although I don't subscribe to that view).
Software should be *more* reliable than hardware, since software has
no inherent failure modes, isn't subject to temperature changes, power
glitches, parts variability or EMI, and is precisely reproducable
times a million copies... no solder joints, no part tolerances. Yet
it's the hardware that's usually most reliable. Software is buggy
because of miserable programming methodologies and practices. Mine's
not.

This is sad: FPGA design, these days, is dominated with struggling
with the software tools, trying to get the compilers to grudgingly
agree to do what you know you want done on-chip, and then trying to
get the compilers to run to completion without crashing. See
comp.arch.fpga: it's mostly about struggling against the tools. The
FPGAs themselves - the hardware - work fine. Xilinx 9.1 is just out -
a 1.5 gig download - and SP1 is already out, another gigabyte. I
wonder if they've fixed any of the memory leaks.

I still wish for FPGA design tools that will let me override the
optimisation settings on a per module (at least) basis - I might have
very good reasons for not desiring to optimise a gate away. Indeed some
tools are, in a phrase I have coined many a time, 'just smart enough to
be stupid'.

Schematic and layout tools have their issues, but given the type of
feedback those vendors get, they aren't nearly as bad as some synthesis
tools.

Cheers

PeteS
 
J

Jan Panteltje

This is a snip from an embedded product program, a combination
thermocouple temperature controller and NMR gradient driver. This is a
sort of printf function.

The program was done in a couple of weeks calendar time, released as
rev A, and has been in production for about a year. There are no bugs.
A bit over 4K lines of assembly. It's an absolute, monolithic assembly
of a single source file, no libs, includes, or linkers involved.

The .SBTTL directive create an entry in the listing's table of
contents.

<snip source>

Yes that is nice, many asm for example for PIC I wrote looks like that
too, with comments after each instruction.

RS232 controlled x,y,z camera position control, and EEPROM presets, with PIC
and auto positioning and auto panning:
ftp://panteltje.com/pub/camcp.asm

Usually takes a couple of hours to write something like that, much of the
time spend inserting PIC in programmer :)
I never use MPLAB or simulation or anything, only a scope.
Maybe made in 10 programming tries....
Revision 0.7.1 revisions mainly added stuff, only a few bugfixes.
This one has lasted years....

Library? What library?
 
R

Robert Adsett

No, the code rules (always) because that is what the processor ultimately
executes.
Up until this day at least, processors do not read books.

So what? Comments aren't executed. Comments are for conveying to the
human reader the reasons for the instructions used. Justifications for
decisions taken, limitations of the routine/approach. To let the reader
know what is supposed to happen and how ro use the routines in question.
Sometimes the explanation will, of course, be too involved to include in
the comments in its entirety and in that case they may refer to external
references such as standards texts and of course lab book derivations.
So, many funny comments have been written, and sometimes not releated to what
a function does at all.

And banks are robbed. Theft is however, still illegal. Just because
people don't take the discipline to do something properly does not mean
it should not be done. And I don't intend to hold myself up as a
paragon of virtue in that regard either, part of the discipline of
programming is continually correcting bad habits. And comments must be
maintained just as the code does.

A source code file more nearly resembles a schematic than it resembles a
layout. It's at least as much about communicating intent to the human
as it is about communicating to the compiler.
I understand and appreciate your post, but in the simple example that John gave
the C code says it all, at least for me, so I even skip the comments.

So can I. That doesn't mean they shouldn't be there. And part of his
complaint as well as a big part of mine is that the larger more complex
functions are even worse.

As an example the header in one file contains the following

* FILE: lib/crtdll/conio/kbhit.c
* PURPOSE: Checks for keyboard hits

And the first function starts as

int fflush(FILE *f)

Now either they've used very bad practice and fflush check for keyboard
hits, or the header is completely at odds with the body. It would be
laughable it it weren't tragic. If it were an isolated case it could be
just a simple error and would hardly be worth this complaint, although
it should still be corrected. It is not isolated though.

So, I am not shy with comments :)

I'm not saying you are. Just that the commenting in the example John
was given was poor. Unfortunately it appears the other examples on the
same site are worse. Not much wonder John dislikes C if that's what
he's got to go on.

Robert
 
Top