Comments

[PlainName]

Why does no-one write comments any more? Not even just something to say what the function is meant to do, never mind the intricacies of how it goes about that. Some cryptic 12-character name may mean something to the programmer but it's bugger-all use when coming afresh to get a birds-eye view of things.

And variables! Really, do babies die or something if you let on WTF a variable is about?

[golden_labels]

Not sure, what you mean. In particular your “anymore” suggests there is some shift in the situation from some previous different state. Which I do not really see. If anything, in the past 20 years programmers started to at least write docs for documentation generators. It often sucks and misses the point of an API documentation, but it is still better than 20–30 years ago, when there was nothing. So… clarify?

[bpiphany]

Reaction video for two opinions in one


Lengthier take on comments

[woody]

Well, not no-one.

I recon that at least 80% of the characters I type in any given program is part of a comment. If not more. My latest project has 22 functions, 652 statements and 1918 comments. Sometimes my code reads like a book 

Mind you, this is pure self-preservation, for if I look at anything I wrote that is not part of a project I am currently working on, I often don't have a clue what I meant. Might be either age or fluctuating brilliancy.

Paul

[madires]

I'm writing plenty of comments, mainly for myself. It makes maintaining the code much easier. And as a side effect it also helps others to understand what is happening. When you contribute to a larger project without any comments you'll have to waste a lot of time to get into the code.

[PlainName]

Well, not no-one.

Well done

What triggered this was idle wondering about writing a TOPT/HTOP program (for myself, to do what I want rather than what some other person thinks they wanted). And there was a link to the KDE Locksmith program on github. I figured I could just pop in to see what the process is minus the machine and UI specific parts, and from there went to various forks or other sources. Not one had comments other than the boilerplate copyright stuff at the top. Names were meaningless unless you're already into what it does and how it fits together. Just some comment on a function saying briefly what the function does would help. Saying why it does it, and why that might be useful would be fantastic but will never happen.

I don't really care if the comments are out of date. If/when I need to debug the code I will be looking at the code. An out of date comment is still useful because it tells me the history, and what the stuff once did (or was meant to do). Like getting the schematic for a model B power supply when you're trying to fix a model A - it's all good if that's the only stuff around.

So I wondered if the lack of comments, generally, has some overriding benefit other than laziness on the part of the programmer.

[Function comments serve another purpose too: they effectively - visually - mark where functions start and end, which helps when paging through.]

[xrunner]

Why does no-one write comments any more? ...

Probably because they hung around a guy I used to have to associate with at work. He worked in another dept. and wrote some C software for a project we were trying to get to operate correctly. I was looking at the code and it was simply undecipherable in the whole. I asked him to explain it to us because there were no comments at all. He said he didn't need to because it was "self-documenting". Anyone who understood C should be able to follow it and understand. If you can't do that then you don't understand programming and shouldn't be trying to help.

 

[madires]

Ouch! It's mostly about algorithms, not the programming language. Of course, there are many standard algorithms without much need for comments. However, there's also complex and thinking-outside-the-box stuff hard to comprehend, even with comments.

[dietert1]

People with little experience tend to believe they finished things and no one will ever touch their code again. A self-fullfilling prophecy, as code without comments tends to be junked rapidly. If people want to be part of a team, they have to talk to each other.
Another problem are comment stripping tools used in the open source community for IP reasons.

Regards, Dieter

[golden_labels]

I still don’t see, how is that different from the past, as implied in the opening post. I will ignore this part and only respond to the other post.

When you prototype on a breadboard or even make a hobbyist one-off design, do you produce project reports, write essays on the behavior of each segment, and finish it with a polished datasheet? Or are you focused on making it work and then continue to the next design? So don’t expect anything more from programmers.

Non-commercial FOSS projects are often done by volunteers in their free time. And documenting things, which are obvious to you at the time of writing the code, is not the first priority in this process. It is a tedious task, which does not contribute to achieving the goal. The only benefit is long-term and depends on meeting a condition: that the comments are good. This condition is rarely true, as writing good comments is an art. Try contributing to a FOSS project by providing documentation: after half a year, when the burnout hits, you will see what I mean. Having good documentation is also not well understood among people with insufficient experience. Just like many other beliefs arising from not being bitten enough by own mistakes, after 20+ years I still haven’t come across a method to correct this.

For commercial projects not only the above applies, but there are incentives to not document code. Most notably: you are not being paid for that. Quite opposite: your productivity, measured as finished code output, drops by a factor of 2 or 3. Your employer sees no short-term benefit to writing comments either, and in reality⁽²⁾ only a minor benefit long-term. You are expected to deliver quick and documentation slows you down. If that is not an open project, the code also remains a part of sausage making: whatever shit is in it, it is fine, as nobody from the outside knows.

To be clear: that’s written by a person, who had high docs-to-functional-code ratio. Though in-line comments were quite scarce, as I believe good code is self-documenting. So basically only magic and unobvious relationships were commented on, and some notes were present on potential future traps.

⁽¹⁾ I’m making an assumption here, based on the talk happening on a electronics-focused forum.
⁽²⁾ The reality includes most programmers writing useless comments and a lot of the code being replaced before the comments are of any use.

[PlainName]

When you prototype on a breadboard or even make a hobbyist one-off design, do you produce project reports, write essays on the behavior of each segment, and finish it with a polished datasheet? Or are you focused on making it work and then continue to the next design? So don’t expect anything more from programmers.

So programming is really just hacking without any design consideration? Even a shit and quick breadboard will have a schematic, and typically that will have decent signal labels, comments where appropriate and a good layout. Are they not equivalent to comments?

We are not talking 'documentation' per se - scribbles in the margin would be ok!

Non-commercial FOSS projects are often done by volunteers in their free time. And documenting things, which are obvious to you at the time of writing the code, is not the first priority in this process.

So if they are not being paid then the stuff must be rubbish? Can no-one just take some pride in what they do regardless of remuneration?

For commercial projects not only the above applies, but there are incentives to not document code. Most notably: you are not being paid for that.

What? Never have I had a contract that said anything about comments. They are part of writing code, and I get paid to write code. Thus I get paid to write whatever comments I deem fit to write. I think you're making up justification where none exists.

Though in-line comments were quite scarce, as I believe good code is self-documenting.

Ever heard of executive summaries? That's comments. Code is the detail.

[golden_labels]

So programming is really just hacking without any design consideration? Even a shit and quick breadboard will have a schematic, and typically that will have decent signal labels, comments where appropriate and a good layout. Are they not equivalent to comments?

We are not talking 'documentation' per se - scribbles in the margin would be ok!

“Without any design consideration” is way too strong. But not neccessarily formal design happening outside of programmer’s head. For most part programming is nothing more than translating from an imprecise concept expressed in human terms to a precise language understood by a machine. Proper engineering is rare. Not out of laziness or the lack of skills, but because overwhelming majority of problems a programmer has to “solve” are not requiring engineering.

Putting it in electronics terms: if a 50th client wants you to create what boils down to a single indicator LED circuit, are you doing any proper engineering? Or do you just eyeball a resistor suitable for the LED and supply voltage? Without leaving any comments? Virtually all tasks a programmer faces now in the industry are of that kind. Often more complicated as a system, but easily decomposed to such trivial tasks.

Don’t get me wrong. Proper engineering and design, with actually inventing solutions, is still a thing. But this is a minority of cases.

So if they are not being paid then the stuff must be rubbish? Can no-one just take some pride in what they do regardless of remuneration?

This is not what I wanted to say. Time is not made of rubber. If somebody donates their free time (a limited resource) to make something useful, they focus on making this thing work rather than secondary aspects. Patience and the will to help are also draining fast, so they are rather spent on rewarding activities, not the tedious tasks with relatively little value, which by most newbies are not even seen as needed.

Imagine you volunteer in an animal shelter. It’s a hard work, but you assume it’s a mix: some harships, some pleasure, contact with animals, getting the feel of being helpful. Now imagine that, upon arriving there, you are mostly being sent to do (human) toilet cleaning, driving back and forth with supplies/waste, and removing snow from the entrance. A work that certainly is required for an animal shelter, somebody has to do it, but this is probably not what you wanted to donate your free time to. This is different, if you are simply hired there to do the job.

What? Never have I had a contract that said anything about comments. They are part of writing code, and I get paid to write code. Thus I get paid to write whatever comments I deem fit to write. I think you're making up justification where none exists.

You could assume I am making a justification, if I was defending anything. But that is unlikely, given that I already mentioned my stance on comments. Right? To add to it: through my entire career I spent exactly zero seconds in office. All my jobs were commisioned, so nobody cared when I do them and how much time I spend. I could afford my perfectionism speak through my code as long as I deliver before deadlines. But I was an exception, not the rule, and I try to answer your question for the general case.

There is nothing in your contract. But if your managers notice you spend 1/2 to 2/3 of your worktime not producing anything they see as valuable, what do you think is going to happen? Do you imagine them being happy about that? Or how would you compare to these new outsourced collegues, who suddenly work 2× faster than you? Note that I am not talking about adding a single line of comment once in 100 lines of code, but writing proper, rich documentation.

Ever heard of executive summaries? That's comments. Code is the detail.

From my perspective: if I need to describe the code, the code is wrong and I need to fix it. With the aforementioned exceptions.

Using the above terminology to describe writing extensive comments: it would be as if I wrote executive summary of the same size as the full report. The chapters titles in the full report (function/method/variable names) and their abstracts (function/method/class documentation) should be sufficient to skim over the code and understand, what it does.

[rhodges]

I often write notes in a project journal to keep a history of what I am thinking and doing. Here is an example from a semi-recent code to convert binary to decimal on the CH32V003, which does not have multiply, divide, or DAA.

Here are my journal notes:

Code: [Select]

Thinking about binary to decimal conversion on the non-M RISC-V MCUs (such as
the CH32V003), the usual way of using DAA and the full and half caries is not
going to work here.

Going to the last library for the STM8, one function does the DAA in multiple
instructions. To start, it assumes that the DAA add-6 will be necessary and
subtracts it back out if it turns out not. Also, this is done before the left
shift, so actually 0x33 is added so that the 0-9 BCD digits will stay in the
4 bit range. Also, adding the 3 to the 0-9 BCD value will set bit-3 (value of
8 or higher) when the DAA is needed (originally 5-9). We can use this bit test
to decide if the DAA is needed.

Idea: On the RISC-V code, we can add 0x33333333 to the 32-bit BCD result
register, assuming that all 8 digits will need DAA. Then check the high bit
of each BCD result and undo the add if the bit is clear (original digit was
0 to 4). What if we AND the result with 0x88888888 to get the DAA decision
bits, XOR to invert, shift right by 2 to get correction*2, shift right to
get correction*1, then subtract the two corrections to get a conditional
subtract 3 for each BCD digit.

RISC-VE has T0-T2 and A0 to A5 available. None of these need to be saved.
Since the BCD DAA is done in parallel, this will be the main conversion
function, and will serve wrapper functions with any number of input bits
and ASCII digits. Note that the binary input must be left aligned.
The "remove leading zero" function will be separate.

Also note that with only 8 ASCII digits, a full 32-bit conversion is not
possible with this code (limited to < 100 million).

For a binary to decimal conversion, this only needs 32+8 loops, and is probably
a lot faster than calling an integer divide (and remainder) function ten times
and then converting to ASCII and storing. YES! If the RISC-V MCU has a hardware
divide, that would be a better choice. But the CH32V003 does not, so this has
to be done with simple opcodes.
And here is the code in question:

Code: [Select]

/******************************************************************************
 *
 *  Binary (up to 32 bits) to ASCII (up to 8 digits)
 *
 *  in: binary, digit buffer, bit count, digit count
 */

void binx_decx(uint32_t bin, char *dec, int bits, int digits)
{
    asm(
        "li      t0, 32                 \n"
        "sub     t0, t0, %2             \n" /* 32 minus bit count. */
        "sll     %0, %0, t0             \n" /* Left justify bits. */
       
        "li      t0, 0                  \n" /* BCD digits */
        "li      t1, 0x33333333         \n" /* DAA add (pre-shift) */
        "li      t2, 0x88888888         \n" /* DAA correection bit mask */
        "j       2f                     \n"

        /*  Do the left shift and DAA  */
        "1:                             \n"
        "c.add   t0, t1                 \n" /* assume DAA */
        "and     a5, t0, t2             \n" /* get correction bits */
        "xor     a5, a5, t2             \n" /* invert correction bits */
        "srli    a5, a5, 2              \n" /* correction *2 */
        "sub     t0, t0, a5             \n"
        "srli    a5, a5, 1              \n" /* correction *1 */
        "sub     t0, t0, a5             \n"
        "slli    t0, t0, 1              \n"

        /* Add the high binary bit to the BCD */
        "2:                             \n"
        "srli    a5, %0, 31             \n"
        "c.add   t0, a5                 \n" /* add 0 or 1 */

        /* Shift in the next binary bit */
        "slli    %0, %0, 1              \n"

        /* Loop until done */
        "c.addi  %2, -1                 \n"
        "bnez    %2, 1b                 \n"

        /* All BCD digits are done now. */

        "c.add   %1, %3                 \n" /* Start with lowest digit. */
        "sb      zero, (%1)             \n"
        "3:                             \n"
        "c.addi  %1, -1                 \n"
        "andi    t1, t0, 15             \n" /* Get BCD digit. */
        "addi    t1, t1, '0'            \n" /* Make ASCII. */
        "sb      t1, (%1)               \n"
        "srli    t0, t0, 4              \n" /* Rotate in next BCD digit. */
        "c.addi  %3, -1                 \n"
        "bnez    %3, 3b                 \n"
        :
        : "r" (bin), "r" (dec), "r" (bits), "r" (digits)
        : "t0", "t1", "t2", "a5"
        );
}

/*
INPUTS:
A0: binary input
A1: pointer for ASCII decimal result
A2: number of bits to process (loop counter)
A3: number of BCD digits to process (loop counter)

Working registers:
T0: BCD building register
T1: 0x33333333
T2: 0x88888888

A5: BCD correction register
*/


[Karel]

Anyone who understood C should be able to follow it and understand.
If you can't do that then you don't understand programming and shouldn't be trying to help.

I agree.

 

[JPortici]

I don't comment much. I try to write code that is self explanatory (and in short functions with meaningful names) with variables with meaningful names.
I do comment what the function does before the function if needed, and i try to do it in oneliners. If it doesn't it's probably worth it to separate into multiple smaller functions, or refer to a UML state chart diagram. I do comment on the purpose of variables in structures, padding elements, magic numbers (though you shouldn't use magic numbers if possible) and the like

Usually i am the only one that has to read the code and sometimes i have to reread the code i wrote years ago. Thankfully i've got good enough at commenting that i don't have to damn past me to hell anymore but to be honest, i could do better in case someone else has ever to get on board and contribute

[PlainName]

For most part programming is nothing more than translating from an imprecise concept expressed in human terms to a precise language understood by a machine.

That's the ultimate aim, but 'programming' is much more than that. It's like saying making a cake is just shoving ingredients in a pan, cooking it and Bob's your uncle. But what about cleaning up after? What about keeping the cooker functional and clean? Organising your recipes so you can find the right one. Etc. Programming without appropriate comments is like leaving burnt shit splattered over the inside of the microwave, and having to clean your tools every time before you can start to cook.

if a 50th client wants you to create what boils down to a single indicator LED circuit, are you doing any proper engineering? Or do you just eyeball a resistor suitable for the LED and supply voltage?

For a homer that only I will see, probably the latter. For a client, it will be the correct resistor.

If somebody donates their free time (a limited resource) to make something useful, they focus on making this thing work rather than secondary aspects

That's wrong. If you can only time to bodge a job then I don't want you going anywhere near it. Go and find something you do have the time to do.

And apart from that, where is your pride in a job well done?

Imagine you volunteer in an animal shelter. It’s a hard work, but you assume it’s a mix: some harships, some pleasure, contact with animals, getting the feel of being helpful. Now imagine that, upon arriving there, you are mostly being sent to do (human) toilet cleaning, driving back and forth with supplies/waste, and removing snow from the entrance. A work that certainly is required for an animal shelter, somebody has to do it, but this is probably not what you wanted to donate your free time to.

Don't have to imagine that. If it's not something I can do properly I don't do it. If I do it, I do it to the best of my ability regardless of what it is. And if someone needs to do something in a project, and you've volunteered for that project, that someone is you.

But we're not discussing doing completely different things to what you volunteered for. Commenting is as much programming as using tabs (or spaces) and not having 20 statements on a single line, etc. Fixing it so there are no compiler warnings (and not taking the quick shortcut of silencing the compiler).

From my perspective: if I need to describe the code, the code is wrong and I need to fix it.

How on earth can you make a variable name describe what the variable is for, any limits on its values, where and why you might use it, etc? And, most important, wtf it's for. Same with functions - you cannot have 76-character function names and still have legible code, and that function name still won't convey the essential info, nor will it describe what the parameters do or even why you need them.

[PlainName]

Anyone who understood C should be able to follow it and understand. If you can't do that then you don't understand programming and shouldn't be trying to help.

Tree and forest problem.

Look at keysmith.cpp for instance. Is that going to be useful to me? Does it tell me how this thing works at a summary level? You're saying I have to read through every single line and build my own mental model of what this code does, and only after figuring that out can I ask my original question of whether this could be useful. If there were comments I could speed read and decide whether or not to devote any more time to it.

[xrunner]

Anyone who understood C should be able to follow it and understand. If you can't do that then you don't understand programming and shouldn't be trying to help.

Tree and forest problem.

Look at keysmith.cpp for instance. Is that going to be useful to me? Does it tell me how this thing works at a summary level? You're saying I have to read through every single line and build my own mental model of what this code does, and only after figuring that out can I ask my original question of whether this could be useful. If there were comments I could speed read and decide whether or not to devote any more time to it.

No I"M not saying it the person I worked with said it. You didn't even quote my post in full! 

[PlainName]

OK, that wasn't clear. Feel free to pass my comment on to them 

[PlainName]

You didn't even quote my post in full!

Full quoting is stupid and inappropriate. I quoted the exact bit I was commenting on, and if it's not in that quote then I wasn't commenting on it. You can easily look at the original if you need or want to, but it makes no difference because nothing else in your original post is relevant to what I was commenting on. Otherwise I would have included it, see.

[xrunner]

You didn't even quote my post in full!

Full quoting is stupid and inappropriate. I quoted the exact bit I was commenting on, and if it's not in that quote then I wasn't commenting on it. You can easily look at the original if you need or want to, but it makes no difference because nothing else in your original post is relevant to what I was commenting on. Otherwise I would have included it, see.

You should have included my member name in the quote at least. Where did you get your forum manners?

[alm]

How on earth can you make a variable name describe what the variable is for, any limits on its values, where and why you might use it, etc? And, most important, wtf it's for. Same with functions - you cannot have 76-character function names and still have legible code, and that function name still won't convey the essential info, nor will it describe what the parameters do or even why you need them.

If you need 76 characters to describe what a function does, then the function is probably doing more than one thing and should be split up. Same with variables, parameter names, etc. If you're programming in assembly, or in FORTRAN 77 with a 6 character limit on variable names. Back then comments were essential. But the problem with comments is that they'll often fail to get updated when code gets updated. So then you get code like this:

Code: [Select]

// return TOO_MANY_BOTTLES error if there are more than 5 bottles
int check_for_too_many_bottles(int number_of_bottles) {
  if (number_of_bottles > 3) {
    return TOO_MANY_BOTTLES;
  }
  return 0;
}

I'd rather name variables, functions and constants. If one line of code is really complicated, it should probably be its own function with a clear name. The advantage is that function and variable names are more likely to be updated since they are part of keeping the code working. If I rename the function in one place, I'll have to rename it in another place if I want the code to compile. Very likely the IDE will handle this. None of this applies to comments. Putting in a comment where a variable or function is not very helpful, since usually this will change over time, and the comment is unlikely to be updated. Better use the IDE to find references.

This is different if you're documenting an external API, like in a library. Then the interface should be relatively stable, so updating documentation shouldn't be such a hassle.

[Rerouter]

I write enough that I wont curse myself in 3 months, but I don't go for monolith functions so its usually not that hard to read,
Usually things like // Yes this is dumb, its a workaround for a library compiler error

If things are starting to seem weirdly complex, I'll usually remake the part to keep the complexity in the 1 spot, and stop it spreading,

[PlainName]

You didn't even quote my post in full!

Full quoting is stupid and inappropriate. I quoted the exact bit I was commenting on, and if it's not in that quote then I wasn't commenting on it. You can easily look at the original if you need or want to, but it makes no difference because nothing else in your original post is relevant to what I was commenting on. Otherwise I would have included it, see.

You should have included my member name in the quote at least. Where did you get your forum manners?

Mate, how do you know I quote YOU if I didn't tag is as from you? You just assumed. And in fact said you didn't say that, so....

How about having a barney at Karel who not only didn't quote your full post but included you name to boot?

Frankly, I don't give a shit who said what I quoted, or where. I am commenting on the view expressed by the entirety of that quote. Nothing more, nothing less. If you want to claim ownership that's fine, but if you don't that's fine too and I'll pretend I completely made it up just to be able to express my opinion on that exact phrase.

Besides all that <breath....> full quoting is wrong and lazy. The only two reasons to include a full quote is because it's short and sweet, or you want to record it for posterity in case the original gets edited. To do otherwise is to metaphorically say "you're too dumb to just scroll up the page if you're to dim enough to understand the succinct quote".

I suggest you browse around the intertubes for quoting etiquette.

[xrunner]

Mate, how do you know I quote YOU if I didn't tag is as from you? You just assumed. And in fact said you didn't say that, so....

LOL! How do I know? BECASUE I WAS THE PERSON THAT WROTE IT!

Oh my gosh!       

[PlainName]

So have a go at Karel too, then. Or are you scared you might upset him?

But, better, see Dave's take on it.

[xrunner]

Where did he say it's a good idea to leave the member's name and link back to the post off of a quote?

See what you wrote here -

Anyone who understood C should be able to follow it and understand. If you can't do that then you don't understand programming and shouldn't be trying to help.

Tree and forest problem.

That's just a ridiculous and poor quoting habit. You need to lose that one. 

[PlainName]

None so blind...

You are deflecting. It was about full quotes, not attribution.

[xrunner]

None so blind...

You are deflecting. It was about full quotes, not attribution.

It can be about anything I want it to be about at any time I wish. You seem to not like your bad habits being pointed out it seems. 

[tggzzz]

Why does no-one write comments any more? ...

Probably because they hung around a guy I used to have to associate with at work. He worked in another dept. and wrote some C software for a project we were trying to get to operate correctly. I was looking at the code and it was simply undecipherable in the whole. I asked him to explain it to us because there were no comments at all. He said he didn't need to because it was "self-documenting". Anyone who understood C should be able to follow it and understand. If you can't do that then you don't understand programming and shouldn't be trying to help.

 

That's the modern religion. It has a little validity in that, presuming the code is tasteful and literate, there is a good chance the comment will become out of sync with the code.

It completely ignores the concept that, even with tasteful and literate code, a comment should indicate "why" and "contextual use".

[ataradov]

I don't write comments because I personally don't like reading them. The first thing I do when trying to understand unfamiliar code is strip the comments and see what the code does. This does not apply to the API documentation, of course.

At the same time I just write readable code and my expectation is, if you can't read it, you probably would not be able to use it anyway.

[xrunner]

It completely ignores the concept that, even with tasteful and literate code, a comment should indicate "why" and "contextual use".

Well if it is written

x = a + (b / c);

of course any person can read and understand what that does - what is the calculation mathematically. What it doesn't tell us is why does the program need to get a value for x from those variables? What is being accomplished?

What this guy thought was you can understand what the program does by reading these lines one by one and understanding what the program is accomplishing with no comments at all. Of course given enough time you could ... but who has all that time for a very complicated program?

[ataradov]

Very complicated program would have a lot of comments in that case. And realistically it is better to read the code rather than novels about the code.

And you should be able to understand what the code does from the function name. If you have a huge wall of text function, then again, it is more of a programming style issue rather than comment issue.

It is fine if the comment says something like "calculate offset of the button on the screen". But if it goes into describing every single detail about that calculation, it would be a drag to read.

[alm]

x = a + (b / c);

Unless a, b and c were variables that made sense in some specific domain, I'd say this is bad code. How about:

Code: [Select]

int calculate_x_offset(int margin, int text_length, int character_width) {
  return margin + (text_length / character_width);
}
Would you still need a comment?

What this guy thought was you can understand what the program does by reading these lines one by one and understanding what the program is accomplishing with no comments at all. Of course given enough time you could ... but who has all that time for a very complicated program?

At the top is a function like draw_graph(). This already tells you a graph is being drawn. Then this function will call other functions to draw axes, the points, labels, etc. To get a gist of it, just look at the top level functions. Let's say it reads like this:

Code: [Select]

function draw_gui() {
  draw_sidebar();
  draw_graph();
  draw_console();
}

So by just reading this, I learned that the code is drawing a GUI consisting of a sidebar, graph and console. You probably don't have to look at how text is being rendered or how an UART is initialized to understand what a program is doing. Since functions should be organized from high level to low level, just stop reading whenever you have reached the level of detail that you needed to know.

[xrunner]

Yes alm that is very bad code because the variables are not explanatory. But that is just about as bad as some complicated software I've seen written for the area I worked in, i.e. not for sale outside the company. If the variables are well named of course it helps understanding what the lines of code are for, what they are calculating to achieve a desired outcome in the control of equipment or the screen display of data for the user.

[ataradov]

Ok, but then we should not say "let's write good comments", but simply "let's write good code". Why write bad code and then good comments to explain that bad code?

And people that write bad code, won't be any better at writing comments anyway.

[Siwastaja]

Good commenting has always been scarce. Even "known good" code is often commented like this:
i++; // i is increased by 1
while it lacks real comments, like large pieces of text which explains how the interface is used, and why the module is designed like it is.

Probably programmers are irrationally afraid of writing large comments because someone has told them, in the past, that this should be a "separate documentation". Fair enough, but if they don't write that "separate documentation" while writing the code, they will never come back to write it, and no one else will do it either. Therefore it is safest to write every piece of documentation that comes into mind as code comments. You can always later refactor them into a separate document if the line count seems to explode, you start needing images and ASCII art does not cut it...

Commenting single lines all over the code base indicates some fundamental problems:
* Hopefully just tendency to write unnecessary comments. Harmful, but they can be ignored
* Tendency to write code which is so messy it needs such comments
* Inability to do good naming. Why write:
  float a; // this is acceleration
  when you can write
  float acceleration;

I have been shocked to see how poorly the interfaces of some widely used libraries are documented. It seems all the effort goes into satisfying the Doxygen syntax, and then the actual content is missing. "Oh, we listed the parameters and the autogenerated html looks professional, job done". Fuck these guys. As a C programmer, I absolutely need to know if the function makes copy of the data pointed by ptr, or if I, the caller, need to keep the buffer allocated. If this information is missing, then the library is unusable, documentation is completely broken. And it often is.

[tggzzz]

Very complicated program would have a lot of comments in that case. And realistically it is better to read the code rather than novels about the code.

And you should be able to understand what the code does from the function name. If you have a huge wall of text function, then again, it is more of a programming style issue rather than comment issue.

It is fine if the comment says something like "calculate offset of the button on the screen". But if it goes into describing every single detail about that calculation, it would be a drag to read.

Oh, you lucky person. Now you can have more fun in your life by reading https://thedailywtf.com/series/code-sod

The front page contains links to classic articles.

Personally I use the RSS feed.

[tggzzz]

Ok, but then we should not say "let's write good comments", but simply "let's write good code". Why write bad code and then good comments to explain that bad code?

And people that write bad code, won't be any better at writing comments anyway.

Occasionally it is beneficial to write a comment to explain why apparently bad code is actually appropriate.

The existence of bad programmers writing bad comments does not make comments bad. After all, while "all crows are black birds" it does not follow that "all black birds are crows".

[bpiphany]

Snapshots from above video. Write good documentation, not comments. (And good code of course.)

[magic]

How about:

Code: [Select]

int calculate_x_offset(int margin, int text_length, int character_width) {
  return margin + (text_length / character_width);
}
Would you still need a comment?

I still have no idea what margin is, why would you add to it what appears to be the number of characters in text, and what the resulting offset is supposed to be.

edit
Actually, wtf, text_length is not text_width, so is it character count? What would be the point of dividing that by character width?

And this is a perfect example why you guys are insane. Your code is clearly buggy, and without comments I have no idea how to fix it.
Is it supposed to be multiplication and the resulting offset in pixels? Perhaps inches or millimeters?
Is it supposed to be text_width, with margin and the result in units of characters?
Something else that hasn't occured to me yet but will, if I spend an hour trying different things and inspecting all call sites?
(In reality: the function is undocumented, so different call sites assumed different things, it's all FUBARed and only "worked" by luck and insufficient testing).

Pro tip: If I'm reading your code, it often is because either the code or something connected with it is screwed up. I probably already know what the code is doing before reading it because I see the effects, so thank you very much. What I don't know is what it was supposed to do differently, and in which place.


Or how about this example I just wrote:

Code: [Select]

#define MEG 0x100000

// read buffer, must be page aligned, MEG is safe overkill
#define BUF (16*MEG)
__attribute__(( __aligned__ (MEG)))
char buf[BUF];
versus equivalent self-descriptive code

Code: [Select]

#define MEG 0x100000
#define BUF (16*MEG)
__attribute__(( __aligned__ (MEG)))
char sixteenMBbuffer_page_aligned_actually_MEG_aligned_becasue_Im_lazy[BUF];

[PlainName]

The first thing I do when trying to understand unfamiliar code is strip the comments and see what the code does.

That's an interesting approach (and pity the reverse can't be done!) . Do you just do that when you are working on the code, or if you're just browsing to get an overview too?

[PlainName]

Ok, but then we should not say "let's write good comments", but simply "let's write good code". Why write bad code and then good comments to explain that bad code?

And people that write bad code, won't be any better at writing comments anyway.

What is 'good code'? In the sense of being able to understand it, I mean. We go on about suitable names for functions and things, but thinking up those names can be really difficult. I know I have trouble achieving that on the fly. And the problem is that even fantastic names don't tell us why, only what.

[PlainName]

It seems all the effort goes into satisfying the Doxygen syntax, and then the actual content is missing.

Yep, more than once I've had my hopes raised by great-looking documentation actually existing, only to find it's completely useless doxygen output. And typically they also leave out the call tree diagrams too.

[Karel]

IMO, assuming the software comes for free (free as in speech, not as in beer), choose one of the following options:

• Pay somebody (ideally the original programmer) to write/improve the comments.
• Write/improve the comments yourself
• Use the software and accept the bad comments.
• Do not use that software.

Things that we should not do IMO:

• Whining about it
• Shaming the programmer

 

[Nominal Animal]

All of the above is why I tell learners to focus on writing comments that describe their intent, instead of describing the code.



When I implement a standard Xorshift64* pseudo-random number generator, I simply name it.  When I only use the 32 to 40 high bits of its output, I mention that that way the output passes the full BigCrunch randomness tests, and is thus "better" than e.g. Mersenne Twister (MT19937).

In multithreaded code, I use comments to describe the locking schemes.  For standard pthread_mutex_t protecting a set of variables, I mention that where the variables are declared, but for anything more complicated, I mention the scheme is described in an external document (LOCKING, typically).

If I implement an easily rehashed hash table or say a disjoint set data structure, I describe it as such, and try to explain why it was chosen (by describing the most important features, and most unimportant downsides).  There is no need to explain standard abstract data structures internals; only if one deviates from standard data structures.  For example, if you create a thread-safe binary tree, you definitely need to describe the locking scheme and its limitations, especially wrt. node deletions and concurrent traversal.

For embedded/microcontroller code accessing hardware, it is nice to have a root-level block comment describing where that hardware is documented, especially when multiple subsystems are used.  (Say, an interrupt and DMA-driven SPI interface, and its latency and interrupt priority requirements.)

There is absolutely no way to reliably infer developer intent from the code itself.  The code is the result, not the design; and any particular feature –– or even the overall approach –– may be an unintended error, or more commonly, a misunderstanding or a "thinko": a logic bug/error similar to a typo.  These happen to every single human programmer.

When dealing with code without comments describing the developer intent, I always have to try and infer that first.  It is a heuristic process, and therefore prone to errors.  Anyone claiming they don't write comments because they don't think they are necessary, needs to be hit with a cluebat.  The true purpose of comments is to provide the information the code does not provide, and that is intent.  Only when the intent is known, can one compare the implementation to the intent.  Even then, either one can be faulty!  When the intent is not documented at all, it can only be inferred from the code, which takes time and adds another possible source of errors.

When I am trying to fix or extend others' code, my most common thought is "what the hell did the author of this crap think when they wrote this?"
because in a vast majority of cases, problematic code could be simplified by switching to a better algorithm/approach.  This definitely applies to my own code as well, because "good code" is not simply written once and then put out there.  Truly good code evolves through refactoring and algorithmic optimization.  Sure, if you intend to write a piece once and never touch it again, you can omit any comments and write documentation that satisfies the client, but such code is never, ever truly "good"; not when compared to code that has been refactored and competed with other possible implementations.

This is why documenting the developer intent matters: it provides the information needed to fix/enhance/refactor the code in the longer term, allowing it to evolve instead of just accumulate/aggregate into a larger, more complex whole.  If your refactoring increases rather than decreases the complexity of the whole, you are doing it wrong.  Having to try and heuristically infer the developer intent from the code is unnecessary waste of effort, because the intent can always be described in simple, short comments.  Not even trying to write them in the first place is, well, kicking extra work onto others because you're too lazy to do your own bit.

[madires]

Some very simple code:

Code: [Select]

  TCNT1 = 0;
  TCCR1A = (1 << WGM10) | (1 << COM1B1);
  TCCR1B = (1 << WGM13);

If you know that MCU's registers well you might be able to tell what is done here. Otherwise you would have to spend some time reading the datasheet.

Now with comments:

Code: [Select]

  /*
   *  set up Timer1 for PWM
   *  - phase and frequency correct PWM
   *  - top value by OCR1A
   *  - OC1B non-inverted output
   */

  TCNT1 = 0;                            /* set counter to 0 */

  /* enable OC1B pin and set timer mode */
  TCCR1A = (1 << WGM10) | (1 << COM1B1);
  TCCR1B = (1 << WGM13);

Some lines further down OCR1A is set and the timer enabled (by setting the prescaler).

[PlainName]

Just noticed an excellent example:

https://www.eevblog.com/forum/kicad/handcrafted-footprints-for-kicad

OK, it's not C but if you are hip to the language (and who wouldn't be if you're using Kicad) the comments still make a LOT more sense than the raw code without. Hell, even I could see what the thing does with just a couple of seconds of speed reading, and I use Altium!

[Siwastaja]

Snapshots from above video. Write good documentation, not comments. (And good code of course.)

The problem with this mindset is that unless you make it 110% absolute sure that the separate documentation is
A) written in the first place,
B) maintained,
C) easily available, easy to find, easy to access, easy to read,

this just reduces into not having the documentation at all since "I can't put it in comments".

If you document interface functions properly in the .h file (for example), then I can, in an IDE or code editor, see this documentation automagically as I write code. I have never seen an interface function being documented too well. The opposite problem, too little, is usual. Once properly documented in code comments, automated tools such as doxygen can be used to create the separate documentation for those who prefer to have it, so it's a win-win.

And it's no only about interfaces. If I want to look at why the implementation is like it is, of course I would be looking at the code anyway. Once I have the code file open, why not have documentation there? Of course this isn't a substitute for project-wide documentation which for example explains how the modules interact.

[SiliconWizard]

All of the above is why I tell learners to focus on writing comments that describe their intent, instead of describing the code.

Yes.

[tggzzz]

There is absolutely no way to reliably infer developer intent from the code itself.  The code is the result, not the design; and any particular feature –– or even the overall approach –– may be an unintended error, or more commonly, a misunderstanding or a "thinko": a logic bug/error similar to a typo.  These happen to every single human programmer.

Yes, and it isn't confined to software.

I was once given the job of converting a TTL design to the new-fangled PALs. That's very difficult if you don't know which bits of functionality a 7492+3*7474+gates are actually using. It is much easier if you know it is a swallow counter, or whatever.

Basically not knowing what something is supposed to be doing leads to "reimplement it all including the bugs".

The true purpose of comments is to provide the information the code does not provide, and that is intent. 

I like to point out that good comments enable you to accurately ignore 99.9% of the code, and quickly focus on the 0.1% that needs attention.

[Nominal Animal]

There is absolutely no way to reliably infer developer intent from the code itself.  The code is the result, not the design; and any particular feature –– or even the overall approach –– may be an unintended error, or more commonly, a misunderstanding or a "thinko": a logic bug/error similar to a typo.  These happen to every single human programmer.

Yes, and it isn't confined to software.

Very true.  Even when just optimizing some workflow, the key is to find the intent/purpose of the whole workflow, instead of trying to micro-optimize the already chosen approach.

I like to point out that good comments enable you to accurately ignore 99.9% of the code, and quickly focus on the 0.1% that needs attention.

I have to (try to) write such comments because of exactly this.  It reduces my cognitive load, and lets me spend my meager brain resources on the important stuff.

It is one of my biggest regrets, that I learned the usefulness of good comments so late in my programming career.  It is damned difficult to try and learn later on; you cannot just "tack" that on top of an existing programming knowledge, it has to be "built in" to work well and come out naturally.  I've found that for languages I learned afterwards, it is much, much easier to learn to write good comments as you learn the ins and outs of the language itself.

For example, consider the following Python Fibonacci sequence generator:

Code: [Select]

def fibonacci(n1, n2, count=None):
    """Generates the Fibonacci sequence starting with 'n1' and 'n2',
       optionally limited to 'count' first elements (minimum 2)."""
    yield n1
    yield n2
    if count is None:
        while True:
            yield n1+n2
            n1, n2 = n2, n1+n2
    else:
        for i in range(2, count):
            yield n1+n2
            n1, n2 = n2, n1+n2
If you save that as say fibo.py, and run pydoc3 fibo, you'll see
    FUNCTIONS
        fibonacci(n1, n2, count=None)
            Generates the Fibonacci sequence starting with 'n1' and 'n2',
            optionally limited to 'count' first elements (minimum 2).

To print the first 1000 Fibonacci numbers, one per line, you could use
    for n in fibonacci(0, 1, 1000):
        print(n)

This is the kind of "intent" I'd like to see in code comments.  The wording may feel odd when reading the docstring in the source code, but I like to use pydoc3 myself to see a quick synopsis of the interfaces a Python file provides, and "tune" the wording to read "best" that way.
As to how to best name such generator functions in Python, whether one should use type hints, et cetera: those are language-specific details best discussed elsewhere.

[tggzzz]

There is absolutely no way to reliably infer developer intent from the code itself.  The code is the result, not the design; and any particular feature –– or even the overall approach –– may be an unintended error, or more commonly, a misunderstanding or a "thinko": a logic bug/error similar to a typo.  These happen to every single human programmer.

Yes, and it isn't confined to software.

Very true.  Even when just optimizing some workflow, the key is to find the intent/purpose of the whole workflow, instead of trying to micro-optimize the already chosen approach.

Agreed.

Even if not taught it explicitly, any engineer ought to rapidly come to realise that they should listen to their customers stated desires in order to understand their needs. As I've put ir elsewhere... Don’t ask “Can you give me a lift into town?” Do ask “Can you give me a lift into town, so I can replace my broken frobnitz?”. The answer might be “There’s a spare frobnitz in the attic”, thus saving time, money, the environment – as well as making some space in the attic.

It also applies to salesmen and marketeers. In order to be able to effectively sell something to your customer, you have to understand what they give to their customers (and what they receive from their suppliers). That enables you to be able to say buy my X and it will help you persuade your customers to buy more of your stuff.

[SiliconWizard]

Yes, although one may question what is meant by "intent" exactly. Sometimes the developer's intent is not even completely known to themselves. While the intent is usually thought of as a willingness to implement some specififcation correctly, that may not necessarily be entirely the case, or, unfortunately way too often, the specififcation may itself not be accurate, or may not even exist at all. other than very informally.

So, there are even more reasons to consider that the code is definitely not proper documentation of what should be. But one may argue that it is the best possible documentation of what it *is*, which is kind of obvious, but often what people mean by documentation.

But comments? Yes, comment the what and why, and the how only if it's something particularly clever, otherwise refrain. Also, I recommend commenting when fixing a bug that was not an obvious bug, to document it. Main reason is to avoid anyone else looking at the code later on (or even yourself, after a while) reverting back to a buggy version that may look more obvious, but was the buggy approach to begin with. Relatively frequent when working on largish code bases in teams.

[bpiphany]

Of course the self explanatory code require a language and context that supports it. Low level C and the low level likes probably isn't that.

I'm not a low level programmer. But just an excerpt from my latest attempt. Found some new AVR aliases(?) for the register bits and things. Makes the names a bit more informative. And at the next abstraction layer up from that giving names and variables explanatory names should be perfectly possible.

Code: [Select]

#define BAUD_RATE 56700
#define USART0_BAUD_RATE (((float)F_CPU*64/(16*(float)BAUD_RATE))+0.5)
inline static void init_usart(void) {
  PORTMUX.CTRLB |= PORTMUX_USART0_bm;   /* Alternative pins for USART0 */
  PORTA.DIRSET   = PIN1_bm;             /* TX-pin output */
  PORTA.DIRCLR   = PIN2_bm;             /* RX-pin input  */
  USART0.CTRLA   = USART_RXCIE_bm;      /* Enable interrupt on recieve */
  USART0.BAUD    = (uint16_t)USART0_BAUD_RATE;
  USART0.CTRLC   = USART_CMODE_ASYNCHRONOUS_gc
                 | USART_PMODE_DISABLED_gc
                 | USART_CHSIZE_8BIT_gc;
  USART0.CTRLB   = USART_TXEN_bm
                 | USART_RXEN_bm;
}


[Nominal Animal]

Yes, although one may question what is meant by "intent" exactly. Sometimes the developer's intent is not even completely known to themselves.

I'm using the word 'intent' for intention, goal, plan, purpose; with emphasis on plan, as in overall design.
(The case where the developer doesn't have an overall plan or intent for the code, I call "throwing spaghetti code at the wall and seeing what sticks".)

While the intent is usually thought of as a willingness to implement some specification correctly

No, that's on a different level of complexity, something that belongs in the supporting documentation, in my opinion.

But that does bring up a really important point/question: What is the proper level of complexity for useful comments?

Ataradov wrote in reply #30 that they don't write comments, and that they often rip them out before analysing code.  I think that is most likely due to having had to work too much with code with useless and counterproductive comments, because they indeed do more harm than good.  My own preference differs, but I don't like fixed rules requiring comments either.  To me, they're annotations about what the developer is trying to achieve; important when used correctly, worse than useless when used incorrectly.

If you implement a command-line sort-like utility for some specific data you often use, and instead of reading the data into an array you use a self-organizing data structure (tree, heap) to minimize the human-observable latency (rather than minimizing CPU time used, because you cannot start sorting an array before it is completely read), this overall design is something that belongs to the documentation, and not somewhere in the comments.

That is, the overall purpose and approach of the code belongs to the documentation, and not in the comments.  So that puts a "ceiling" on the level of complexity.  And the code itself already tells us what it does, and repeating that in comments is definitely not useful, putting an even clearer "floor" on the level of complexity.

In my opinion, we need to assume understanding of (or capability to find out about) algorithms and known named approaches. For example, if you implement code that calculates Newtonian trajectories for particles in 2D or 3D using velocity Verlet integration, you should only need to name it in a comment; and not try to explain in the comments how velocity Verlet integration works.  Whether one describes velocity Verlet integration in the documentation depends on the overall purpose: I would only do that myself for scientific software (in a separate LibreOffice or LaTeX source file plus .pdf output file).

A majority of cases where I've found comments to be useful is when they describe expectations, especially unusual or not-easily-inferred ones.
Locking (threads, files, databases) is particularly common.  Another is typical parameter values/ranges, when an approach is used that is really fast and precise for almost all cases, and only falls back to a "slow" code path for unusual parameters; and this choice is based on profiling. ("Profiling shows X=Y in 99% of calls, so algorithm Z is used here.")

I also count "use [foo algorithm] to do [bar]" as an "expectation" in the above paragraph.  It is common for algorithm implementations to miss some corner cases.  A typical one is binary searches when the data contains duplicates: most implementations return one of the matching entries if found, and not necessarily a specific one (like the first one of the repeated values).

So, there are even more reasons to consider that the code is definitely not proper documentation of what should be. But one may argue that it is the best possible documentation of what it *is*, which is kind of obvious, but often what people mean by documentation.

True.  It is often this shift, switching from what the code does, to type a concise comment about any surprising/unexpected/un-inferrible choises made related to the purpose/intent/plan for the code, that makes writing good comments so hard.

(It is also why I believe it is easier to learn to write good comments when one learns that particular programming language or its general approach, rather than later on.  We humans are creatures of habits, and learning new habits is hard when one has to (even partially) un-learn a previous habit first.)

Also, I recommend commenting when fixing a bug that was not an obvious bug, to document it.

Most definitely.  If you find something unexpected or obscure about the code, and fix or verify it, add a comment about it!

I warmly recommend the common format of starting such comments with the ISO date (YYYY-MM-DD or YYYYMMDD) and username, say
    // 2023-12-31 nominalanimal: X is correct, because Y.
as it makes investigations using source code versioning systems (svn, git, etc) faster.

[coppice]

All of the above is why I tell learners to focus on writing comments that describe their intent, instead of describing the code.

That sounds like a great idea, but we need to deal with real human beings. I've never seen comments consistently try to describe intent. I've only rarely seen them say valuable things like "This bit might seem weird, but it deals with the following non-obvious situation - xxxxxxx". Having spent a good chunk of my career getting screwed up projects back on track, my first step became to use scripts to strip all comments from the code, except for the file headers. The comments rarely agree with the code. They rarely comment on the purpose of the code. They are just dead weight, making what is usually hard to read code, full of meaningless variable names, bulkier to read through. Unless you can find a way to change human nature, I don't see a way to consistently improve on that sad situation. The best I've managed is to get people to be more thoughtful about variable names, so at least those say something meaningful.

[Nominal Animal]

All of the above is why I tell learners to focus on writing comments that describe their intent, instead of describing the code.

That sounds like a great idea, but we need to deal with real human beings. I've never seen comments consistently try to describe intent.

Just because the world is full of shit now, does not mean everything has to be shit, or that the world has to be full of shit forever!

Yes, it is certain that the majority of software will be shit for the foreseeable future.  What I personally try to do, is help those who are interested in producing something other than shit; those who are trying to build something new and useful, rather than get paid to produce more shit to be sold to hapless victims.

There is zero chance of me (or us) changing the majority of programmers, or even a significant fraction of them, but we can help those who are interested in rising above the generic muck, and help make the best in the future better than the best we have now.  That may or may not be sufficient, but it is better than giving up.

The best I've managed is to get people to be more thoughtful about variable names, so at least those say something meaningful.

That's better than nothing, isn't it?  It's not like you've given up on all developers: you're just concentrating on those you can affect.

I mean, this is not something I nag people about in real life, really.  I don't even rant about it face-to-face: after successful projects or problem-solving sessions, I tell anecdotal stories of why I wish so much I'd have learned to write better comments as I was learning to program in general, as it would have saved so much effort and made code maintenance and long-term development so much easier.

And, when discussed, I describe the reasoning for (here, experience leading to) my own opinions.  (My opinion does not matter, but the reasons for my opinions might be useful to others.)


New programming languages are often discussed here and elsewhere.  While C is the most widely used low-level embedded programming language, it is by no means perfect.  I've occasionally discussed what properties a better-than-C language for low-level embedded programming would have (although I've done much more systems programming using POSIX C myself), but I've also mentioned I do not intend to create my own "replacement C" at all: just experimenting with changing the standard C library with something better suited to today's needs suffices for me.  (The ISO C standard splits C into "freestanding" and "hosted" environments, with the standard C library only available in "hosted" environments, and "freestanding" having basically zero runtime and no standard library functions present (except for a few special functions like memcpy(), memmove() that the compiler itself may generate).  Replacing the standard library with your own functions is quite easy, and typically only needs a few compiler and linker flags to be set.  If running under an OS, you do need to implement a syscall interface for each specific hardware architecture and OS using e.g. inline assembly, but it's all quite straightforward.)

That is the exact same thing: not an effort to change everything or everybody at once, but make it possible for the future to be made better than it is now by those who are interested in it.  Help and advice, not demand and require; and in small enough bites to be practical.

[coppice]

New programming languages are often discussed here and elsewhere.  While C is the most widely used low-level embedded programming language, it is by no means perfect.  I've occasionally discussed what properties a better-than-C language for low-level embedded programming would have (although I've done much more systems programming using POSIX C myself), but I've also mentioned I do not intend to create my own "replacement C" at all: just experimenting with changing the standard C library with something better suited to today's needs suffices for me.

That is the exact same thing: not an effort to change everything or everybody at once, but make it possible for the future to be made better than it is now by those who are interested in it.  Help and advice, not demand and require; and in small enough bites to be practical.

An interesting thing about most new languages is they keep following the syntax of C, which is horrible. Before C a lot of languages had learned the benefits of things like "endif". "endwhile", etc. reducing the ambiguity about the scope of constructs. C didn't learn from that experience, and most people follow the mistake blindly. If you've had to fix broken projects, you'll know how many would have been less broken if the syntax forced greater clarity on the page.

[Nominal Animal]

New programming languages are often discussed here and elsewhere.  While C is the most widely used low-level embedded programming language, it is by no means perfect.  I've occasionally discussed what properties a better-than-C language for low-level embedded programming would have (although I've done much more systems programming using POSIX C myself), but I've also mentioned I do not intend to create my own "replacement C" at all: just experimenting with changing the standard C library with something better suited to today's needs suffices for me.

That is the exact same thing: not an effort to change everything or everybody at once, but make it possible for the future to be made better than it is now by those who are interested in it.  Help and advice, not demand and require; and in small enough bites to be practical.

An interesting thing about most new languages is they keep following the syntax of C, which is horrible. Before C a lot of languages had learned the benefits of things like "endif". "endwhile", etc. reducing the ambiguity about the scope of constructs. C didn't learn from that experience, and most people follow the mistake blindly. If you've had to fix broken projects, you'll know how many would have been less broken if the syntax forced greater clarity on the page.

Sure.  Point is, I don't have the resources or charisma to convince others to switch from C to something else, much less a new programming language of my own design regardless of how good it would be technically.  Very few others are experimenting with just replacing the standard library part with a different, incompatible library, one more suited to current needs.  So, instead of trying to maximize the breadth of change I might affect, I'm concentrating on the small part where I might make the most positive impact, no matter how small in breadth.  A small step at a time.

The situation with code commenting is similar.  Quantitatively, we can only affect a tiny fraction of developers, at best.  However, because that tiny fraction is exactly those who are interested in their skill and art enough to try and do better, they are disproportionately more likely to write code that matters (that may even impact our future selves), so trying to help them in useful-sized bites –– like advice on commenting when suitable –– is worthwhile.

It's all about picking your battles with true long-term in mind.

[nctnico]

If you document interface functions properly in the .h file (for example), then I can, in an IDE or code editor, see this documentation automagically as I write code. I have never seen an interface function being documented too well. The opposite problem, too little, is usual. Once properly documented in code comments, automated tools such as doxygen can be used to create the separate documentation for those who prefer to have it, so it's a win-win.

Not really as doxygen can't show how everything fits together in the big picture. A long time ago I had to take a project over from a co-worker who got a burnout (he stayed sick for over a year). Needless to say there was no handover and I had no knowledge about the project at all. It litterally got dumped onto my lap. The single thing that helped me most to get going with this project was a diagram that showed how all the pieces work together and how the data flowed between them. Doxygen can't generate that kind of information. Personally I loath programmers who present doxygen generated crap as the project documentation as it doesn't tell me anything. Loading the project into an modern IDE is much more worthwhile as the IDE typically can show things like call hierarchies and where functions and variables are declared.

[PlainName]

Not really as doxygen can't show how everything fits together in the big picture.

I think it can if you set it up appropriately.

[SiliconWizard]

Yes, of course Doxygen will show you call graphs. That's one of its basic features. Not that I find Doxygen particularly good either (or rather, the way it's often used), but if people are going to judge it, they may as well know what it can or cannot do.

[tggzzz]

Not really as doxygen can't show how everything fits together in the big picture.

I think it can if you set it up appropriately.

... and then you invoke a function indirectly through an entry in a table of function pointers. In other words, one of the classic ways of implementing FSMs. Or callbacks. Or vtables. Or a generic test algorithm passed to a generic library function (e.g. a sort()  ). Or...

[coppice]

Not really as doxygen can't show how everything fits together in the big picture.

I think it can if you set it up appropriately.

... and then you invoke a function indirectly through an entry in a table of function pointers. In other words, one of the classic ways of implementing FSMs. Or callbacks. Or vtables. Or a generic test algorithm passed to a generic library function (e.g. a sort()  ). Or...

Even something as generally thorough as Ghidra still struggles to highlight all those situations, even though it should be able to see things like tables with a bunch of addresses matching the entry points of a bunch of routines.

[SiliconWizard]

Note that some guidelines such as MISRA prevent the use of function pointers, IIRC. Not saying that I agree, but just saying that these are often thought of as a bit too slippery for safety-critical stuff.

[tggzzz]

Not really as doxygen can't show how everything fits together in the big picture.

I think it can if you set it up appropriately.

... and then you invoke a function indirectly through an entry in a table of function pointers. In other words, one of the classic ways of implementing FSMs. Or callbacks. Or vtables. Or a generic test algorithm passed to a generic library function (e.g. a sort()  ). Or...

Even something as generally thorough as Ghidra still struggles to highlight all those situations, even though it should be able to see things like tables with a bunch of addresses matching the entry points of a bunch of routines.

Void* and equivalents mean all bets are off; anything can happen. Especially if something cannot be determined statically as it is only instantiated at runtime.

Languages which are strongly and statically typed go a long way to helping IDEs analyse codebases. People that only know C (or C++) rarely understand just how powerful and accurate "cntl-space" auto-completion can be at determining the complete set of legal possibilities at any specific point in the code.

[coppice]

Note that some guidelines such as MISRA prevent the use of function pointers, IIRC. Not saying that I agree, but just saying that these are often thought of as a bit too slippery for safety-critical stuff.

MISRA is short for MISRAble. Its a horrible mix of good and bad practices. I wonder if the net effect contributes to safety or danger?

[nctnico]

Note that some guidelines such as MISRA prevent the use of function pointers, IIRC. Not saying that I agree, but just saying that these are often thought of as a bit too slippery for safety-critical stuff.

From the last time I checked, I recall that constant function pointers are allowed. In most cases the interrupt vector table is just that... But also think about state machines and command line interpreters where having function pointers greatly simplifies the code.

[PlainName]

where having function pointers greatly simplifies the code

It can simplify the code, but make it harder to figure out what's going on when what's going on isn't the expected going on.

[madires]

... and that can be explained in comments.

[PlainName]

 

[Siwastaja]

where having function pointers greatly simplifies the code

It can simplify the code, but make it harder to figure out what's going on when what's going on isn't the expected going on.

Yeah. I never understood the fear of using a function pointers instead of enumerations. With a variable and, say, switch-case, you can check for some illegal values, but not if the wrong value is from the legal set, and that's the most realistic bug. The fear that the function pointer corrupts to any random value pointing in random place in memory is of course valid, but if you have memory corruption to begin with, then it's equally likely to do similar hard-to-understand damage (e.g., corrupt a return address) even if you don't use function pointers. Replacing function pointers with something else adds memory safety by maybe 0.001%. Instead, proving absence of overindexing, zero termination mistakes etc., which can be done, would easily catch 99% of memory-corrupting bugs.

If you want fair level of protection (say, >90%?) against the rest, or uncontrollable memory corruption (e.g., due to radiation), that is going to require significant effort everywhere in the code base. Avoiding function pointers would be just the tip of the iceberg.

I recall that constant function pointers are allowed.

If true, this sounds to me that these guys had absolutely no idea what they are doing. Because function pointers being constant, but still in memory, doesn't help against memory corruption caused by bugs (say, serious overindexing) or external sources at all. The only thing it does, it helps against the bugs where a programmer accidentally writes an insane value to the function pointer; now the compiler would prevent this write. But that is an extremely weird and remote scenario to begin with; it would require typecasting and is obvious even in mediocre code review. And if we go this far, what prevents the programmer to cast away the constness anyway?

The bug which actually happens, is the programmer enters a valid, but wrong state; and for this bug type, const function pointers or enumerated state values are exactly the same.

[nctnico]

By constant I (and the designers of MISRA) mean a variable sits in read-only memory. Not RAM. Typically everything you declare const in C on a microcontroller ends up in flash which is read-only.

From my experience the biggest cause of memory corruption are buffer overruns. So allowing function pointers in read-only memory only, is a sensible compromise IMHO. At least you won't get the situation that code is executed from a random address.

[jfiresto]

... If true, this sounds to me that these guys had absolutely no idea what they are doing. Because function pointers being constant, but still in memory, [only] ... helps against the bugs where a programmer accidentally writes an insane value to the function pointer; now the compiler would prevent this write....

Allowing function pointers in a variable makes it hard to catch certain bugs through static analysis. I recently had to do something like that, for a dead simple, three-line Python class, to stop a static code checker (pylint) from misinterpreting the Abstract Syntax Tree and complaining about calling arguments for a method the caller was not calling.

[golden_labels]

Only MISRA may give their reasons.

But in general function pointer arrays in comparison with switch have close to no benefits. Due to limitations of C syntax, the code may be a bit more concise. But that’s it.

In terms of performance both are compiled to very similar machine code.switch version has no branching, though nowadays branching in most circumstances is not inflicting heavy penalty.⁽¹⁾ Function pointers array is opaque to optimizers, but potential optimizations are scarce even for the switch option. Depending on specific architecture either may increase footprint, but by a negligible amount. So here neither of the solutions has consistent advantage.

The disadvantages of function pointers arrays are, however, notable. From security perspective it must involve a machine instruction, which takes an arbitrary variable value as its parameter. This is an open invitation to RCE, ACE, DoS, and other attacks based on gaining control over program flow. Putting jumps arrays in ROM is of no use, because at machine code level the data from ROM is loaded into RAM or registers, or at least is selected using data in RAM or registers. In comparison switch has no such dependency. From safety perspective, the code is much harder to analyze or prove its validity.⁽²⁾ Static analysis becomes mostly useless, code coverage testing can detect neither all cases, nor dead code.

This of course applies to static code and C. If the situation really calls for a dynamic approach, there is little choice. And the advice is not as strong for similar constructs in other languages, where layers of type safety, abstraction and JIT-ing designed to deal with this kind of dispatch make the risk much lower. Of course safety issues may still remain.

Somebody mentioned that an interrupt vector table is just that. This is comparing apples to oranges. It’s like saying, that goto has no issues, because — after all — at machine level all code is just a bunch of jumps. No, machine level code and human-written code are two different scenarios, with separate set of factors affecting their evaluation. It’s also not as universal. AVR, for example, uses an equivalent of optimized switch.

⁽¹⁾ And a function call is usually much more expensive than branching.
⁽²⁾ It may seem otherwise, if you look at your own code and a trivial situation. To see, what I am referring to, try reverse-engineering (or even understanding source) code of somebody else, where indirect invocation is involved in a project of hundred source files.

[coppice]

By constant I (and the designers of MISRA) mean a variable sits in read-only memory. Not RAM. Typically everything you declare const in C on a microcontroller ends up in flash which is read-only.

From my experience the biggest cause of memory corruption are buffer overruns. So allowing function pointers in read-only memory only, is a sensible compromise IMHO. At least you won't get the situation that code is executed from a random address.

That's true for small embedded controllers, which were the main targets when MISRA started. However, I don't think they distinguish between that situation, and the bigger systems in modern cars where many processors boot from some form of flash into RAM. You may have protection where the relevant segment is declared read only in the MMU, but its not the solid situation you have in a small MCU where anything constant is truly constant, unless the developer screwed up where they allocate stuff really badly.

[magic]

Arrays of function pointers may have close to no benefit over switch statement.

But lists of function pointers are a whole another story
And they make static analysis even more hopeless.

[coppice]

Arrays of function pointers may have close to no benefit over switch statement.

But lists of function pointers are a whole another story
And they make static analysis even more hopeless.

Some compilers turn switch statements into a bunch of function calls, when the "case" values are in a contiguous block.

[SiliconWizard]

Arrays of function pointers may have close to no benefit over switch statement.

Yes. Actually, they are likely to be worse in terms of performance in many cases, and make code potentially more fragile. 'switch' in C yields surprisingly well optimized compiled code with most modern compilers.
People use this approach usually because it looks nicer, but it is harder (to impossible) to statically analyze, and is potentially prone to run-time security issues (if at any point, one function pointer is in a writable memory area, which could get corrupted.) That is less of an issue if you only index a fixed array of function pointers located in a non-writable area (like flash), although you still need to make sure that the index never gets out of bounds, or else the result is not pretty.

Function pointers have many uses though outside of this, more justified, to make code more generic. If the zero-defect bar is not a goal, obviously it's just a matter of benefit/risk ratio, but as long as it is (which you'd hope it is for safety-critical stuff), the idea is to avoid risks altogether when possible, which is the whole idea behind these coding guidelines. They often look overkill to a degree that may appear stupid, but the goal is to avoid running into any risk that can be avoided, even if that means writing pretty "annoying" code.

[PlainName]

To see, what I am referring to, try reverse-engineering (or even understanding source) code of somebody else, where indirect invocation is involved in a project of hundred source files.

This. I was given some quite complex code as an example of achieving some end, and it was really very painful trying to work out what it did, or when, or why.

[tggzzz]

To see, what I am referring to, try reverse-engineering (or even understanding source) code of somebody else, where indirect invocation is involved in a project of hundred source files.

This. I was given some quite complex code as an example of achieving some end, and it was really very painful trying to work out what it did, or when, or why.

And the other

I have seen a commercial product which was essentially a glorified telecoms FSM. As is traditional, it was written in a scrotty little scripting language designed to allow late customer-specific tweaks to the product.

Over the years the FSM had grown so that the if-then-else clauses were in some cases nested 10 deep. Apparently simple changes took months. No, I had nothing to do with that product!

Now, what was that about switches being easy to understand/change?

[PlainName]

A switch doesn't need nested ifs, does it? You could have a switch (event) for each case (state), but the only real hassle in either case (sorry) is that it could be a long primary switch. Still, that doesn't make any difference to the code really, and it's easy to understand: just run down until you get to the state, run through that until you hit the event, there's the function that deals with it (or one or two like statement if it's short'n'sweet). With no effort, you can tell what event is valid in which state(s) to call whatever function(s). And just as easily find what event(s) in which state(s) could call the function you're looking at.

Edit: too obvious to mention, but... you can put comments in there too, in case you need to say why whatever is happening there.

[tggzzz]

A switch is merely syntactic sugar for multiple if statements; they are equivalent.s

What could have been done is irrelevant; what was done is a useful counterexample to the concept that FSMs and switches are easy/simple to understand.

Quite frankly that project was an example of extreme base taste in several dimensions, perpetrated deliberately over many years, with there being business justification for each change. From the point of view of this discussion, so what

It is one example where comments definitely couldn't have helped. And I'm a fan of good comments, and hate the agile/XP religion that claims comments are of negative value!

[coppice]

A switch is merely syntactic sugar for multiple if statements; they are equivalent.s

Yes, but one brings clarity on the page, and the other is much harder to read. If the cases are complex you have no choice but to use a bunch of if-then-elses, although they can be laid out on the page in an unnested manner, to illuminate their switch like quality,

[golden_labels]

tggzzz: if these were nested conditionals, how would you express it in a more readable way in a lookup array? I am aware of perfect hashing approaches, but clarity is the last term I would use to describe them.

… or were you responding to my post… skipping the conditions?

[SiliconWizard]

A switch is merely syntactic sugar for multiple if statements; they are equivalent.s

Yes, but one brings clarity on the page, and the other is much harder to read. If the cases are complex you have no choice but to use a bunch of if-then-elses, although they can be laid out on the page in an unnested manner, to illuminate their switch like quality,

Not just that, but by construction, it's testing a single object against a number of different values, while a sequence of if's can do absolutely anything *and* is by nature a recipe for duplicated code (if just for testing the object). Which absolutely sucks in terms of maintainability.

Nested testing or whatever has absolutely nothing to do with it. It's a completely orthogonal problem. You can call a function to handle each case of the switch, the switch itself can be as clean as that.
The difference with an array of function pointers is that it's statically analyzable and avoids some of the pitfalls we mentioned for function pointers. Another bonus point for the switch is that each case can call a function with possibly different parameters, while with an array of function pointers, they all have to have the same signature. And so you then often resort either to using void * pointers (so no type checking), or passing around convoluted structures with a lot of context in them that most of your functions won't care about (so another source of potential problem, lack of separation of concerns.)

So again, function pointers certainly have good use cases, but not for replacing a switch construct in general, IMO.

[tggzzz]

tggzzz: if these were nested conditionals, how would you express it in a more readable way in a lookup array? I am aware of perfect hashing approaches, but clarity is the last term I would use to describe them.

… or were you responding to my post… skipping the conditions?

Neither.

I was responding to the posts I quoted, or in a few cases to the immediately preceding post.

Do you have sufficient brainpower to remember all the points made by each contributor in all the 85 posts in this thread? I don't.

For a more specific response, please provide the context to your questions.

[Siwastaja]

Typically everything you declare const in C on a microcontroller ends up in flash which is read-only.

That's true for small embedded controllers

Not even there - for example on AVR, every const, even including string literals, will be in RAM because ROM access is weird. For other systems, it's really fifty-sixty situation; maybe nctnico's assumption holds, maybe not. The developer should know, though. Better use exact language here, and if read-only memory is meant, then say so, not "const".

[SiliconWizard]

Typically everything you declare const in C on a microcontroller ends up in flash which is read-only.

That's true for small embedded controllers

Not even there - for example on AVR, every const, even including string literals, will be in RAM because ROM access is weird. For other systems, it's really fifty-sixty situation; maybe nctnico's assumption holds, maybe not. The developer should know, though. Better use exact language here, and if read-only memory is meant, then say so, not "const".

Yep. Especially since where things end up in memory ultimately depends on the linker (thus on the linker script for those linkers that are scriptable, which covers all targets supported by at least GCC and LLVM, and many other compilers too).
It takes a 30 s linker script modification to make all const data, even if the compiler has decided to put it in the typical ".rodata" section, go directly to RAM. Otherwise, yes, some targets with odd architectures are not even flexible enough for that and data may end up in various memory areas for specific reasons.

I've written a small executive for a MCU just a few days ago that puts absolutely everything in RAM, as everything has to execute, read and write in it, so yes, all const data lies in RAM too.

[tggzzz]

Typically everything you declare const in C on a microcontroller ends up in flash which is read-only.

That's true for small embedded controllers

Not even there - for example on AVR, every const, even including string literals, will be in RAM because ROM access is weird. For other systems, it's really fifty-sixty situation; maybe nctnico's assumption holds, maybe not. The developer should know, though. Better use exact language here, and if read-only memory is meant, then say so, not "const".

Yep. Especially since where things end up in memory ultimately depends on the linker (thus on the linker script for those linkers that are scriptable, which covers all targets supported by at least GCC and LLVM, and many other compilers too).
It takes a 30 s linker script modification to make all const data, even if the compiler has decided to put it in the typical ".rodata" section, go directly to RAM. Otherwise, yes, some targets with odd architectures are not even flexible enough for that and data may end up in various memory areas for specific reasons.

I've written a small executive for a MCU just a few days ago that puts absolutely everything in RAM, as everything has to execute, read and write in it, so yes, all const data lies in RAM too.

Yep. Yet another example of someone thinking they know what the C keywords mean.

C has grown so baroquely complex that very few people understand it as well as they think they do - and the people that do know realise how little they know and where the skeletons are buried. C has mutated from its original concept so much that it has become part of the problem (i.e. not the solution).

In the early 90s the C++ committee spent years discussion whether it should be possible or impossible to "cast away const" (needed for debuggers and optimisations, respectively). I believe the decided it should be possible. Does C allow it now? Has that changed over the decades?

[golden_labels]

tggzzz: if a person is commenting on a direct response to my post, I find it reasonable to suspect they did read my post. Perhaps I am old-fashioned and not fitting the modern world.

[tggzzz]

I guess this is the context...

tggzzz: if these were nested conditionals, how would you express it in a more readable way in a lookup array? I am aware of perfect hashing approaches, but clarity is the last term I would use to describe them.

… or were you responding to my post… skipping the conditions?

Neither.

I was responding to the posts I quoted, or in a few cases to the immediately preceding post.

Do you have sufficient brainpower to remember all the points made by each contributor in all the 85 posts in this thread? I don't.

For a more specific response, please provide the context to your questions.

... to which you wrote...

tggzzz: if a person is commenting on a direct response to my post, I find it reasonable to suspect they did read my post. Perhaps I am old-fashioned and not fitting the modern world.

Is it now fashionable to presume that you are the centre of the conversation, and that everybody automatically remembers what you wrote?

Is it no longer fashionable to help the reader understand your point by including the context? In general I have no idea of which of yesterday's (or last week's) posts you are referring to, and am not going to waste my time guessing!

Note that quoting the context is easy: just click the "Quote" button above the post in question.

This forum encourages long subtle conversations by including multiple levels of the context, so it is easy to keep track of multiple sub-threads. Other forums (e.g. stackexchange, edaboard) don't allow multi-level quoting, thereby limiting conversations to boring "which button do I press to turn the splutget's flangle blue?".

Contrariwise this forum enables interesting and subtle on-going conversations, by allowing multi-level quotes in a single thread. That's the nearest currently available to the hierarchical email/usenet readers that were developed to enable people to share opinions and ideas in a distributed world.

[coppice]

In the early 90s the C++ committee spent years discussion whether it should be possible or impossible to "cast away const" (needed for debuggers and optimisations, respectively). I believe the decided it should be possible. Does C allow it now? Has that changed over the decades?

I think that is a natural consequence of evolution. If you ban const being cast away an ENORMOUS amount of great existing code becomes unusable by well written new code. If you allow const to be cast away new code is less robust than it might otherwise be. They probably should have made this a compiler option. Then you can ban it for entirely new clean code, and allow it when you need to interwork. That should have been an easy choice for a committee to agree upon, but too many zealots are usually involved.

[tggzzz]

In the early 90s the C++ committee spent years discussion whether it should be possible or impossible to "cast away const" (needed for debuggers and optimisations, respectively). I believe the decided it should be possible. Does C allow it now? Has that changed over the decades?

I think that is a natural consequence of evolution. If you ban const being cast away an ENORMOUS amount of great existing code becomes unusable by well written new code. If you allow const to be cast away new code is less robust than it might otherwise be. They probably should have made this a compiler option. Then you can ban it for entirely new clean code, and allow it when you need to interwork. That should have been an easy choice for a committee to agree upon, but too many zealots are usually involved.

Not an easy choice, because there are competing important valid forces in each direction.

There was far less existing code in the early 90s, when C (and C++) had to decide whether to be a general purpose programming language or a low level systems language. Either choice would have been valid. In trying to satisfy both, they satisfied neither.

Engineers and the marketplace have chosen that C (and C++) are not the future of general purpose programming languages: too complex to understand and use, too many gotchas, too low level. That leaves close to the silicon and systems uses, and the compromises made for general purpose use have complicated using C there. Hence the rise of Rust, and to a lesser extent, Go.

C will, of course continue, in the same way that COBOL continues. The faster C++ withers, the better.

[coppice]

In the early 90s the C++ committee spent years discussion whether it should be possible or impossible to "cast away const" (needed for debuggers and optimisations, respectively). I believe the decided it should be possible. Does C allow it now? Has that changed over the decades?

I think that is a natural consequence of evolution. If you ban const being cast away an ENORMOUS amount of great existing code becomes unusable by well written new code. If you allow const to be cast away new code is less robust than it might otherwise be. They probably should have made this a compiler option. Then you can ban it for entirely new clean code, and allow it when you need to interwork. That should have been an easy choice for a committee to agree upon, but too many zealots are usually involved.

Not an easy choice, because there are competing important valid forces in each direction.

There was far less existing code in the early 90s, when C (and C++) had to decide whether to be a general purpose programming language or a low level systems language. Either choice would have been valid. In trying to satisfy both, they satisfied neither.

Engineers and the marketplace have chosen that C (and C++) are not the future of general purpose programming languages: too complex to understand and use, too many gotchas, too low level. That leaves close to the silicon and systems uses, and the compromises made for general purpose use have complicated using C there. Hence the rise of Rust, and to a lesser extent, Go.

C will, of course continue, in the same way that COBOL continues. The faster C++ withers, the better.

How is making it user selectable a difficult decision? It allows any view point to be catered for.

The marketplace can't decide what it wants for the future. The last new language to get and hold a strong position was C/C++. Everything else comes and goes, as people realise the latest new thing is no panacea. Python seems to be doing pretty well at the moment, but just a few years ago Java was going quite well, had masses of cash behind it, and has fallen into decline.

[tggzzz]

In the early 90s the C++ committee spent years discussion whether it should be possible or impossible to "cast away const" (needed for debuggers and optimisations, respectively). I believe the decided it should be possible. Does C allow it now? Has that changed over the decades?

I think that is a natural consequence of evolution. If you ban const being cast away an ENORMOUS amount of great existing code becomes unusable by well written new code. If you allow const to be cast away new code is less robust than it might otherwise be. They probably should have made this a compiler option. Then you can ban it for entirely new clean code, and allow it when you need to interwork. That should have been an easy choice for a committee to agree upon, but too many zealots are usually involved.

Not an easy choice, because there are competing important valid forces in each direction.

There was far less existing code in the early 90s, when C (and C++) had to decide whether to be a general purpose programming language or a low level systems language. Either choice would have been valid. In trying to satisfy both, they satisfied neither.

Engineers and the marketplace have chosen that C (and C++) are not the future of general purpose programming languages: too complex to understand and use, too many gotchas, too low level. That leaves close to the silicon and systems uses, and the compromises made for general purpose use have complicated using C there. Hence the rise of Rust, and to a lesser extent, Go.

C will, of course continue, in the same way that COBOL continues. The faster C++ withers, the better.

How is making it user selectable a difficult decision? It allows any view point to be catered for.

The marketplace can't decide what it wants for the future. The last new language to get and hold a strong position was C/C++. Everything else comes and goes, as people realise the latest new thing is no panacea. Python seems to be doing pretty well at the moment, but just a few years ago Java was going quite well, had masses of cash behind it, and has fallen into decline.

Library "maker" chooses one and expects library "user" to take account of that in their code. User doesn't. Variant: the inverse, or someone uses a different library that uses another library. All people in different companies, of course. 

That is all too brittle, and likely to subtly fail. Good luck trying to write unit/regression tests to validate multiprocessor guarantees!

I see no evidence that Java is declining. Sure the fervour is dissipating, which is inevitable when something  becomes the mainstream.

[coppice]

I see no evidence that Java is declining. Sure the fervour is dissipating, which is inevitable when something  becomes the mainstream.

Its hard to say. Java has been driven out of a lot of publicly facing places where its clear what is being used. However, if its still strong in business applications it may have locked itself in, the way COBOL did in my youth, and we wouldn't be all that aware.

[tggzzz]

I see no evidence that Java is declining. Sure the fervour is dissipating, which is inevitable when something  becomes the mainstream.

Its hard to say. Java has been driven out of a lot of publicly facing places where its clear what is being used. However, if its still strong in business applications it may have locked itself in, the way COBOL did in my youth, and we wouldn't be all that aware.

It is strong in enterprise applications, and shows no sign of being superseded. That includes technical areas such as soft realtime telecom and fintech, as well as the obvious database backed web services.

The biggest negative is that Oracle bought Sun, but there are open variants if you don't like your gonads being squeezed.

[SiliconWizard]

I don't quite agree with a couple of your points here, but for a common root reason:

Yep. Yet another example of someone thinking they know what the C keywords mean.

'const' just means that the developer is not allowed to modify the value explicitely in their code. It means nothing else, and indeed assuming anything else is either from a misconception, or from relying on implementation-defined behaviors (which is common when using C). So whether it comes from a misconception or a conscious decision depends a lot on the developer and context. You can just probably assume it's more the former when the person doesn't seem to be able to make that distinction.

C has grown so baroquely complex that very few people understand it as well as they think they do

That's mainly what I don't agree with. C is still very simple. Try to compare its complexity to any modern language. It still has some "quirks" certainly, most, if not all, of them coming from the origins and not ones that have been added along the way. One frequent complaint is about optimizations (which is entirely implementation-defined), but that comes from the misconception that C would be this language that is translated *exactly* as you would write it, which is not what any programmming language does. Heck, even assembly may not be executed in order...

As I routinely say, the main issue with C is not at all that's it's complex, it's the fact that if people don't understand it, it's because they have never learned it. Not because it's complex.
(If anyone thinks C is too complex to learn, please just never touch C++, Ada, Rust, and many others.)
It's a major issue. Many (most?) people using C just assume they can spit out code without ever having learned the language, apart from having followed basic tutorials (yes, even in academia these days) and copied stuff around until that has seemed to sink in. It's almost a miracle that C is still being used successfully in many areas these days, but also makes you understand a bit better why guidelines such as MISRA are unavoidable in some fields, even if that can be considered unfortunate.

The interesting part is that some languages are so inherently more complex than C, that people have literally no choice other than learning them properly before being able to do much of anything with them, which in turn leads to a better command of the language. In other words, that's precisely because C appears so simple that many developers have never bothered to actually *learn* it. The other side, to be fair, being that since C allows you to deal with very low-level stuff, you get the complexity, not of the language itself, but of dealing with low-level stuff. And so people keep asking questions about C when the questions are really about the low-level aspects, that, sure, C doesn't abstract a whole lot (but it's the whole point.)

[tggzzz]

Do not confuse the languages with the standard libraries Java's properties enabled the remarkably rapid creation of complex libraries that had eluded the C++ community for a decade. And, unlike various vendor's C libraries, they all plugged and played nicely with each other.

C is irregular, and has too many "gotchas", i.e. surprises that trip up most programmers.

Java is, by comparison, a simple language where James Gosling took a very well chosen subset of concepts proven over decades, and melded them into a coherent whole. When I read his 1996 whitepaper, I repeatedly said "yes that's what is needed and it will work". C is the heroic sum of many many sticking plasters accredited over the decades. Java is a tasteful collection of concepts, but I will admit some of the newer ones (e.g. Generics) are less pleasing because they are constrained by the JVM axioms.

OTOH the C/C++ community repeated triumphantly reinvents well-known wheels, but makes them ellipical. If you doubt that, consider the belated acceptance that a memory model is necessary!

[magic]

C and Java fill almost disjoint niches. Aren't most JVMs written in C even though most of the rest of the "ecosystem" is written in Java itself?

The "problem" of C is that it sort-of-works for lots of people and there is apparently no one with resources or motivation to develop a clearly superior replacement, if that's even possible. If you try to "clean it up" too much sooner or later somebody will be disappointed and it will turn out that not one but at least a few replacements are needed. To an extent this is already happening with Java/C# displacing C in many applications. C is not defined by C standards, them being more like the lowest common denominator that most (and not even all) vendors reluctantly agree to support. Want a memory model? You have one in every operating system written in C. C is a product of evolution, not intelligent design.

As for Java generics, at least Java has generics, unlike most "C incremented" and "better than C" languages which can't even assign a meaningful type to stdlib's qsort.

[tggzzz]

C and Java fill almost disjoint niches. Aren't most JVMs written in C even though most of the rest of the "ecosystem" is written in Java itself?

The "problem" of C is that it sort-of-works for lots of people and there is apparently no one with resources or motivation to develop a clearly superior replacement, if that's even possible. If you try to "clean it up" too much sooner or later somebody will be disappointed and it will turn out that not one but at least a few replacements are needed. To an extent this is already happening with Java/C# displacing C in many applications. C is not defined by C standards, them being more like the lowest common denominator that most (and not even all) vendors reluctantly agree to support. Want a memory model? You have one in every operating system written in C. C is a product of evolution, not intelligent design.

As for Java generics, at least Java has generics, unlike most "C incremented" and "better than C" languages which can't even assign a meaningful type to stdlib's qsort.

We are in violent agreement with most of those points I particularly like "C is a product of evolution, not intelligent design" and your equating Java with C#-not-Java-honestly.

I am perfectly happy with more than one "replacement" being needed for C. Use the right tool for the job in hand. Use VHDL/Verilog for describing hardware, Macsyma and derivatives when manipulating algebraic equations, R for statistics, etc, etc, etc. The C/C++ community is rife with people who believe that, since you can (eventually) use C/C++ for a problem, C/C++ is all you need to use. Hammers and screws spring to mind

Java generics are sufficient for container classes, and not much more. Useful, but underwhelming. For C++ generics, I'll refer you to the C++ FQA - and we can both enjoy ourselves reading that over the holidays

One neat counter example to the "importance" of the JVM being written in C is Squeak Smalltalk. The last time I looked that virtual machine was written in a subset of Squeak Smalltalk, which makes it very easy to bootstrap the system and to improve the system. Some people will incorrectly claim that doesn't count, since there are two intermediate languages involved: a small subset of C and an assembler language.

Yesterday's news: "With the upcoming Linux 6.8 kernel cycle, the first Rust network driver is set to be introduced." https://www.phoronix.com/news/Linux-6.8-Rust-PHY-Driver

[coppice]

One neat counter example to the "importance" of the JVM being written in C is Squeak Smalltalk. The last time I looked that virtual machine was written in a subset of Squeak Smalltalk, which makes it very easy to bootstrap the system and to improve the system. Some people will incorrectly claim that doesn't count, since there are two intermediate languages involved: a small subset of C and an assembler language.

Time was when a large number of compilers were written in the language they compiled. Cheap computers, and the desire to make compilers multi-platform, kinda killed that, but it had huge benefits. It really kept you focussed on how well your compiler was doing on a complex real world problem - your compiler. Even when computers started to become more affordable and available quite a few compilers were built by using a language that makes the job fairly easy - like Snobol - on another machine, to get a very bare bones compiler going. Then you used that to build a basic native language compiler for the target machine, and moved on to only using the target machine and the native language to further develop. Its excellent discipline.

[nctnico]

Yesterday's news: "With the upcoming Linux 6.8 kernel cycle, the first Rust network driver is set to be introduced." https://www.phoronix.com/news/Linux-6.8-Rust-PHY-Driver

Not sure whether this is a good thing as Rust as a language is pretty obscure. It is good to bring a language that has built-in OO support into the Linux kernel but realistically C++ is a much better choice for the simple reason C++ has been around longer, more people know it and thus make it easier to support the kernel. With Rust only a few can do kernel maintenance so chances are high nobody is going to touch it and the code gets abandoned (especially since the Linux kernel notoriously lacks decent comments).

[coppice]

Yesterday's news: "With the upcoming Linux 6.8 kernel cycle, the first Rust network driver is set to be introduced." https://www.phoronix.com/news/Linux-6.8-Rust-PHY-Driver

Not sure whether this is a good thing as Rust as a language is pretty obscure. It is good to bring a language that has built-in OO support into the Linux kernel but realistically C++ is a much better choice for the simple reason C++ has been around longer, more people know it and thus make it easier to support the kernel. With Rust only a few can do kernel maintenance so chances are high nobody is going to touch it and the code gets abandoned (especially since the Linux kernel notoriously lacks decent comments).

Putting C++ in the kernel would be a disaster. It carries so much baggage with it. I haven't used rust, but I understand it is designed to avoid that baggage, and produce a C like target from OO like source code. If it succeeds in that, then maybe its the real incremental step from C that the name C++ was chosen to imply, and C++ miserably failed to live up to.

[Karel]

On Wed, 5 Sep 2007, Dmitry Kakurin wrote:
>
> When I first looked at Git source code two things struck me as odd:
> 1. Pure C as opposed to C++. No idea why. Please don't talk about portability,
> it's BS.

*YOU* are full of bullshit.

C++ is a horrible language. It's made more horrible by the fact that a lot
of substandard programmers use it, to the point where it's much much
easier to generate total and utter crap with it. Quite frankly, even if
the choice of C were to do *nothing* but keep the C++ programmers out,
that in itself would be a huge reason to use C.

In other words: the choice of C is the only sane choice. I know Miles
Bader jokingly said "to piss you off", but it's actually true. I've come
to the conclusion that any programmer that would prefer the project to be
in C++ over C is likely a programmer that I really *would* prefer to piss
off, so that he doesn't come and screw up any project I'm involved with.

C++ leads to really really bad design choices. You invariably start using
the "nice" library features of the language like STL and Boost and other
total and utter crap, that may "help" you program, but causes:

 - infinite amounts of pain when they don't work (and anybody who tells me
   that STL and especially Boost are stable and portable is just so full
   of BS that it's not even funny)

 - inefficient abstracted programming models where two years down the road
   you notice that some abstraction wasn't very efficient, but now all
   your code depends on all the nice object models around it, and you
   cannot fix it without rewriting your app.

In other words, the only way to do good, efficient, and system-level and
portable C++ ends up to limit yourself to all the things that are
basically available in C. And limiting your project to C means that people
don't screw that up, and also means that you get a lot of programmers that
do actually understand low-level issues and don't screw things up with any
idiotic "object model" crap.

So I'm sorry, but for something like git, where efficiency was a primary
objective, the "advantages" of C++ is just a huge mistake. The fact that
we also piss off people who cannot see that is just a big additional
advantage.
If you want a VCS that is written in C++, go play with Monotone. Really.
They use a "real database". They use "nice object-oriented libraries".
They use "nice C++ abstractions". And quite frankly, as a result of all
these design decisions that sound so appealing to some CS people, the end
result is a horrible and unmaintainable mess.

But I'm sure you'd like it more than git.

            Linus

https://harmful.cat-v.org/software/c++/linus

I still fully agree with Linus.

 

[tggzzz]

Yesterday's news: "With the upcoming Linux 6.8 kernel cycle, the first Rust network driver is set to be introduced." https://www.phoronix.com/news/Linux-6.8-Rust-PHY-Driver

Not sure whether this is a good thing as Rust as a language is pretty obscure. It is good to bring a language that has built-in OO support into the Linux kernel but realistically C++ is a much better choice for the simple reason C++ has been around longer, more people know it and thus make it easier to support the kernel. With Rust only a few can do kernel maintenance so chances are high nobody is going to touch it and the code gets abandoned (especially since the Linux kernel notoriously lacks decent comments).

Torvalds has good taste, IMNSHO, as per Karel's preceding post.

Way back in 1988 I had severe doubts about C++, and everything I have seen since then merely confirms that suspicion. Fundamentally, if C++ is the answer, you asked the wrong question.

In one respect I'm surprised Torvalds is allowing anything other than C into the kernel. In other respects Rust does bring useful possibilities to the table. Maybe I'll even use Rust someday. If it has an ecosystem as interesting, fun, and easy as xC then it shouldn't be too much of a pain

[magic]

Java generics are sufficient for container classes, and not much more. Useful, but underwhelming.

Containers and std::algorithm stuff would already be a big win for the kind of software that gets written in C, but C doesn't have proper generics so it's void* all over the place.

Linux for instance makes wide use of generic containers (lists, hashtables, trees). Each time you iterate over the container you need to know what elements it holds and cast appropriately. Simple type erasure (aka parametric polymorphism, idea as old as C) could tidy up the code and make it robust against oopsies.

A further detail is that these are intrusive containers - you put "struct list_head list;" in your object and the object can be linked into lists by means of pointers in this member object, using completely generic list code which only cares about list_heads. So they also have a "container_of" macro which takes you from a list_head or similar object back to the object which contains it, provided that you know all the types and member names.

Trivial stuff which could be a language feature but isn't, the closest analog being C++ static_cast<> but it only works with that multiple inheritance nonsense, not ordinary aggregates. And it's unsafe, because the language is stupid and has no concept of "struct list_head which is also the member 'list' of struct Foo".

Simple type system extensions like generics and "member element types" could make existing C code cleaner and safer with zero runtime overhead and only minor editing - remove casts, add more sophisticated type annotations. No one appears to be working on such things, save for obscure research languages, mostly functional, so pretty much guaranteed to never gain mainstream acceptance.

For C++ generics

C++ doesn't have generics besides void* it inherited from C and virtual methods, which are syntactic sugar over tables of function pointers that C also has.

C++ has templates, and they do exactly what you'd expect: generate a lot of repetitive code.

Yesterday's news: "With the upcoming Linux 6.8 kernel cycle, the first Rust network driver is set to be introduced." https://www.phoronix.com/news/Linux-6.8-Rust-PHY-Driver

Frustration with C is no reason to fall for Rust hype. Rust was created by C++ developers and as such it inevitably amounts to little more than somebody's favorite "safe subset of C++", because your (stereo)typical C++ developer has never known anything other than C++. This includes C.

Rust has no generics either and what they disingenuously call generics is templates. I am at all unconvinced that this language has any ability to produce efficient and lightweight containers of the sort that Linux uses, without resorting to void* trickery, maybe with "unsafe" prepended to it

There was already an attempt to rewrite Linux in C++.

[coppice]

Way back in 1988 I had severe doubts about C++, and everything I have seen since then merely confirms that suspicion.

When I read the original Bjarne Stroustrup book in the mid 80s I thought it had real potential. It addressed a number of the weaknesses in C, like it bundled both data and its related functions into a class/struct, where they should have been from the start. The problems started when others got hold of it, and there was no longer one person's vision driving it. Even by the time of the first edition of the book he had clearly been pushed to add more than his original vision of a incremental change from C, but it was still looking OK.

Fundamentally, if C++ is the answer, you asked the wrong question.

If the question is "how should I develop this elaborate graphics application", C++ isn't such a terrible answer. The problem is people get so focussed on that type of problem when teaching and thinking about C++ that they've built a system that hammers everything into that mould.

[tggzzz]

Magic's post... https://www.eevblog.com/forum/programming/comments/msg5229423/#msg5229423

Understood and accepted.

I don't think it matters who created Rust, but the more languages they knew the better. The more languages the higher the probability they will extract the good bits and avoid the bad bits. That was very clearly demonstrated in Gosling's 1996 Java whitepaper.

If Rust was only a "simple safe subset" of C++, that would be a beneficial step. Rust adds extra novel capabilities on the form of ownership and non-mutability. That is absolutely vital with today's multicore processors and MCUs. C/C++ is painfully inadequate for those.

[tggzzz]

Way back in 1988 I had severe doubts about C++, and everything I have seen since then merely confirms that suspicion.

When I read the original Bjarne Stroustrup book in the mid 80s I thought it had real potential. It addressed a number of the weaknesses in C, like it bundled both data and its related functions into a class/struct, where they should have been from the start. The problems started when others got hold of it, and there was no longer one person's vision driving it. Even by the time of the first edition of the book he had clearly been pushed to add more than his original vision of a incremental change from C, but it was still looking OK.

Even then it was only good if you hadn't been exposed to the.existing alternatives, Smalltalk and Objective-C.

Having written a small application in Smalltalk to "kick OOP 's tyres", I tried complementing it in Objective-C and C++. The Objective-C version was quickly and easily completed, partly due to its container classes. The C++ version was never completed, partly because of the lack of container classes but more importantly because it forced me to concentrate on irrelevant details and if when I  made an inappropriate choice it was exceptionally difficult to reverse the choices.

I prefer to concentrate on satisfying my objectives, not on satisfying the tool.

It took C++ far far too long to have container classes (or even a String class!), and the tooling was incomprehensible, by all accounts.

Fundamentally, if C++ is the answer, you asked the wrong question.

If the question is "how should I develop this elaborate graphics application", C++ isn't such a terrible answer. The problem is people get so focussed on that type of problem when teaching and thinking about C++ that they've built a system that hammers everything into that mould.

Around 1992 I saw some people develop a GUI for an SDL (i.e. FSM) compiler. (My contribution was merely to create the hardware interface to the HP8920 GSM testset). They spent many man years on the GUI. I could have done something far better and sooner in Smalltalk. Yup, C++ was the wrong starting point for that GUI  application

[coppice]

Even then it was only good if you hadn't been exposed to the.existing alternatives, Smalltalk and Objective-C.

I really disliked Objective-C. The functionality was good, but the way the extra syntax was fudged onto the existing C syntax felt horribly wrong.

Around 1992 I saw some people develop a GUI for an SDL (i.e. FSM) compiler. (My contribution was merely to create the hardware interface to the HP8920 GSM testset). They spent many man years on the GUI. I could have done something far better and sooner in Smalltalk. Yup, C++ was the wrong starting point for that GUI  application

In the 80s a colleague avoided all that hassle. He made some templates for Autocad, to easily draw ITU standard SDL, and a fairly simple program to compile the drawings into the tables for the FSM.

[nctnico]

In the end there is no substitute for competent engineers. But you also need to optimise your choices to the kind of engineers available. For example: I'm not a fan (to put it mildly) of Altium for schematics and PCB design and rather not touch it. But if a customer asks what would be a good package for doing simple PCBs themselves or outsource I can't go around the fact that Altium is pretty much industry standard. So unless there is a good reason to recommend something else, I still recommend the customer to outsource to somebody who uses Altium because the chances are high it is easy to find somebody to take over and/or get an in-house engineer to work on the designs.

[tggzzz]

Even then it was only good if you hadn't been exposed to the.existing alternatives, Smalltalk and Objective-C.

I really disliked Objective-C. The functionality was good, but the way the extra syntax was fudged onto the existing C syntax felt horribly wrong.

Around 1992 I saw some people develop a GUI for an SDL (i.e. FSM) compiler. (My contribution was merely to create the hardware interface to the HP8920 GSM testset). They spent many man years on the GUI. I could have done something far better and sooner in Smalltalk. Yup, C++ was the wrong starting point for that GUI  application

In the 80s a colleague avoided all that hassle. He made some templates for Autocad, to easily draw ITU standard SDL, and a fairly simple program to compile the drawings into the tables for the FSM.

I don't disagree about the syntax, but I've always been more concerned with semantics than syntax. Besides, the message passing paradigm plus inheritance was a major graft onto C, so a major graft onto the syntax didn't seem inappropriate.

(Syntax exception: where whitespace is semantically significant. Think makefiles and Python),

I don't disagree about post processing some other graphical representation; even I had that concept in ~1984 (before I played with Apple Smalltalk on a Fat Mac. Basically anything but C++ seems to be a sound guiding principle

[tggzzz]

In the end there is no substitute for competent engineers. But you also need to optimise your choices to the kind of engineers available. For example: I'm not a fan (to put it mildly) of Altium for schematics and PCB design and rather not touch it. But if a customer asks what would be a good package for doing simple PCBs themselves or outsource I can't go around the fact that Altium is pretty much industry standard. So unless there is a good reason to recommend something else, I still recommend the customer to outsource to somebody who uses Altium because the chances are high it is easy to find somebody to take over and/or get an in-house engineer to work on the designs.

Agreed, but I'm not competent to comment about Altium.

I've always explicitly avoided being in a position where C++ was required.

[magic]

When I read the original Bjarne Stroustrup book in the mid 80s I thought it had real potential. It addressed a number of the weaknesses in C, like it bundled both data and its related functions into a class/struct, where they should have been from the start. The problems started when others got hold of it, and there was no longer one person's vision driving it.

The problem was right at the point when he decided to put code inside data structures, the rest was a consequence.

What you wrote is the basic dogma of object orientation, and it inevitably fails when when you need to do X to two different types A and B. So you have these options:

1. Copy X to both A and B, remember to update both copies when you fix a bug or add features to X. I suppose this can work too...
2. Make X a method of a pointless Xdoer type and reduce types A and B to dumb accessor functions around their data. You are Java.
3. Make X a method of a pointless Xable type and derive types A and B from Xable, which inevitably leads to...
4. Multiple inheritance, because A and C  but not B are actually Yable too, and which may also lead to...
5. Templates, because sometimes loads of pointless types and hidden function pointers behind the programmer's back is too much overhead - ask Java.
6. You are C++ now.

Object orientation is cancer and a poor bandaid over lack of foresight and modularity. In Java it reportedly also serves as a hammer to force at least some modularity on programmers lacking in foresight...

What you actually need is:
1. Modularity - restricting which code accesses which data.
2. Interfaces - common way of manipulating different data by generic code.
3. Flexilibity of implementation - sometimes code duplication may be worth the cost, sometimes a single function pointer is enough and there is no justification for dragging along vtables with each piece of data. In some cases this necessitates choosing between languages, like C++ vs Java.
4. Sensible defaults and a way of changing them when justified would be the holy grail.

C actually comes close to the holy grail, but it lacks syntatic sugar for these techniques, lacks templates, and some argue that it makes bypassing abstract interfaces too easy.

[tggzzz]

...
C actually comes close to the holy grail, but it lacks syntatic sugar for these techniques, lacks templates, and some argue that it makes bypassing abstract interfaces too easy.

C also adds some other characteristics, including baked in undefined behaviour and implementation behaviour that continues to catch programmers out, the ability to treat a camel as if it is a horse,  poor multithread/multiprocessor capabilities, and a complexity that confuses compiler creators.

You can argue the first isn't a problem, iff you only employ "Lake Woebegon"[1] programmers, and they either write all the code in their application or they ensure all libraries are written by Lake Woebegon programmers. Good luck with that!

You can argue the second isn't a problem provided you can prove that a camel==horse in the specific circumstances, and that mistakes reliably cause traps, and that all hardware functions perfectly. Good luck with that! If you can do all that, then you might also be able to spelunk core dumps to figure out what was going on.

You can argue the third isn't a problem with the latest language standards, provided you are allowed to use them and the tools have correctly implemented the language and that the memory model is correct in the hardware you are using.

You can argue the last isn't a problem, provided you don't know where the skeletons are buried because you haven't been in the position of having to fault-find other intelligent programmer's code over decades. Nick MacLaren was in that position at the University of Cambridge where (as always) the High Performance Computing requirements pushed the avallable hardware and software to the limits. He was regularly approached by compiler writers asking him to explain what the standards meant! FFI, see the comp.lang.c and comp.arch usenet archives.

[1] where all children are above average

[magic]

This was a rant specifically about modularity, abstraction and object orientation. In this context the disadvantages to Java are arbitrary (and widespread) type casting and lack of syntactic sugar. The disadvantages to C++ are very primitive code generation facilities.

I'm not going to end every post about C with a full list of things that people consider wrong with C

UB is idiotic, as is the fact that both ISO and compiler vendors consider it acceptable instead of at least IDB, lack of memory management is considered dealbreaker by most, some features are obsolete relics of PDPwhatever assembly language,  you need to memorize operator precedence to understand type declarations, ...

[PlainName]

...
C actually comes close to the holy grail, but it lacks syntatic sugar for these techniques, lacks templates, and some argue that it makes bypassing abstract interfaces too easy.

C also adds some other characteristics,
...
[1] where all children are above average

Didn't you leave out some context from that quote?

[tggzzz]

This was a rant specifically about modularity, abstraction and object orientation. In this context the disadvantages to Java are arbitrary (and widespread) type casting and lack of syntactic sugar. The disadvantages to C++ are very primitive code generation facilities.

I'm not going to end every post about C with a full list of things that people consider wrong with C

UB is idiotic, as is the fact that both ISO and compiler vendors consider it acceptable instead of at least IDB, lack of memory management is considered dealbreaker by most, some features are obsolete relics of PDPwhatever assembly language,  you need to memorize operator precedence to understand type declarations, ...

At least with Java it is impossible to have incorrect type casting. Most incorrect typecasts never even reach the compiler, since the strong typing allows the IDE "cntl-space" to avoid suggesting them. Any incorrect typecasts that cannot be detected at compile time will be trapped at runtime. Then an IDE or stacktrace leads to the cause of the problem, unlike a coredump that was corrupted an arbitrary time in the past.

I'm not so worried about the PDP11's assembler being codified in C syntax. Far more problematical is the PDP11's processing power and "primitive" compiler technology still "corrupting" C's semantics.

[tggzzz]

...
C actually comes close to the holy grail, but it lacks syntatic sugar for these techniques, lacks templates, and some argue that it makes bypassing abstract interfaces too easy.

C also adds some other characteristics,
...
[1] where all children are above average

Didn't you leave out some context from that quote?

Yes, quite explicitly, and with a direct pointer to the full post and a direct pointer to the source of the quote.

Which bit do you consider important to the point I made?

[PlainName]

...
C actually comes close to the holy grail, but it lacks syntatic sugar for these techniques, lacks templates, and some argue that it makes bypassing abstract interfaces too easy.

C also adds some other characteristics,
...
[1] where all children are above average

Didn't you leave out some context from that quote?

Yes, quite explicitly, and with a direct pointer to the full post and a direct pointer to the source of the quote.

Ah, I hadn't realised one had to deliberately not quote the full thing.

Which bit do you consider important to the point I made?

No idea. Perhaps if you'd just quoted that part I'd know.

[magic]

I don't think it matters who created Rust, but the more languages they knew the better. The more languages the higher the probability they will extract the good bits and avoid the bad bits. That was very clearly demonstrated in Gosling's 1996 Java whitepaper.

If Rust was only a "simple safe subset" of C++, that would be a beneficial step. Rust adds extra novel capabilities on the form of ownership and non-mutability. That is absolutely vital with today's multicore processors and MCUs. C/C++ is painfully inadequate for those.

I never said it's simple and it isn't. Maybe simpler than C++ by the looks of it, but that's not saying much and it isn't worth much unless you are migrating from C++ rather than C. My recollection of reading their documentation and tutorials was "lots of language features, lots of jargon, lots of cryptic syntax" and you won't get far without being familiar with it all because the features are tangled with each other and widely used. Deciphering Rust code made me feel like I'm reading STL headers.

The part about knowing other languages and extracting good bits from them is actually ironic, because what I forgot previously is that Rust designers were apparently ML fanboys too as the language borrows a bunch of syntax from there. ML has generics, but Rust chose templates and code generation as the answer to everything.

My impression is that it's at best a "sidegrade" from C. May fix some problems, will create others.

[coppice]

When I read the original Bjarne Stroustrup book in the mid 80s I thought it had real potential. It addressed a number of the weaknesses in C, like it bundled both data and its related functions into a class/struct, where they should have been from the start. The problems started when others got hold of it, and there was no longer one person's vision driving it.

The problem was right at the point when he decided to put code inside data structures, the rest was a consequence.

What you wrote is the basic dogma of object orientation, and it inevitably fails when when you need to do X to two different types A and B. So you have these options:

1. Copy X to both A and B, remember to update both copies when you fix a bug or add features to X. I suppose this can work too...
2. Make X a method of a pointless Xdoer type and reduce types A and B to dumb accessor functions around their data. You are Java.
3. Make X a method of a pointless Xable type and derive types A and B from Xable, which inevitably leads to...
4. Multiple inheritance, because A and C  but not B are actually Yable too, and which may also lead to...
5. Templates, because sometimes loads of pointless types and hidden function pointers behind the programmer's back is too much overhead - ask Java.
6. You are C++ now.

Object orientation is cancer and a poor bandaid over lack of foresight and modularity. In Java it reportedly also serves as a hammer to force at least some modularity on programmers lacking in foresight...

What you actually need is:
1. Modularity - restricting which code accesses which data.
2. Interfaces - common way of manipulating different data by generic code.
3. Flexilibity of implementation - sometimes code duplication may be worth the cost, sometimes a single function pointer is enough and there is no justification for dragging along vtables with each piece of data. In some cases this necessitates choosing between languages, like C++ vs Java.
4. Sensible defaults and a way of changing them when justified would be the holy grail.

C actually comes close to the holy grail, but it lacks syntatic sugar for these techniques, lacks templates, and some argue that it makes bypassing abstract interfaces too easy.

So, you are a deranged fanatic? No middle ground allowed? There are functions so generic they shouldn't be bundled with anything, and there are functions so specific they really should be bundled with the only structures they can possibly work with. Bundling function declarations with the only structures they make sense with is a good practice, used by a number of entirely non-OOP languages which came before C. It can massively speed up getting familiar with code if the implicit association of a function with its related data structures is clearly signalled. I've been there a number of times, and hoped long and hard that the original developers have a painful time on the toilet. Sod comments. They are unreliable, and 5 years in will be mostly misleading. Signalling that gets compiled has to be what the final code is really about, and is a HUGE boon for clarity. I'm highly suspicious of people who use the term "syntactic sugar". They are usually people writing obtuse code, badly laid out on the page, which is easily screwed up by the odd misplaced bracket that is hard to count your way through and check. Syntax means little to a machine, but is means a HUGE amount to a developer trying to keep things clear.

[magic]

At least with Java it is impossible to have incorrect type casting. Most incorrect typecasts never even reach the compiler, since the strong typing allows the IDE "cntl-space" to avoid suggesting them. Any incorrect typecasts that cannot be detected at compile time will be trapped at runtime.

That's still lame. Are there really legitimate reasons to even permit downcasting an Animal to a Horse (only to find that it was a Camel after all)?
Surely sounds like at least a violation of the OO dogma.

Then an IDE or stacktrace leads to the cause of the problem

Stack traces lead to the cause of the problem as surely as call graphs show the full extent of control flow

[tggzzz]

At least with Java it is impossible to have incorrect type casting. Most incorrect typecasts never even reach the compiler, since the strong typing allows the IDE "cntl-space" to avoid suggesting them. Any incorrect typecasts that cannot be detected at compile time will be trapped at runtime.

That's still lame. Are there really legitimate reasons to even permit downcasting an Animal to a Horse (only to find that it was a Camel after all)?
Surely sounds like at least a violation of the OO dogma.

Before Java had generics, downcasting was unavoidable every time you pulled something from a container class. Unpleasing and unsatisfactory, and generics help in that use case

Nowadays the use cases are going to be far more restricted and containable (ho ho). Reflection and demarshalling are the obvious cases.

Then an IDE or stacktrace leads to the cause of the problem

Stack traces lead to the cause of the problem as surely as call graphs show the full extent of control flow

All you have to do is guess which of the many possible paths actually occurred this time Plus, of course, the call graph doesn't contain the offending data, whereas the stacktrace can be inspected to find it.

Good luck using a debugger on an arbitrary C stack trace, especially with -O3 etc

One of the better feature of the JVM is that it is permitted to cheat like crazy provided it isn't visible outside the JVM. That enables HotSpot "profile guided optimisations" to occur on the fly and without the application programmer being aware of whether or not it is happening. Think of HotSpot as being JIT on steroids, or data dependent peephole optimisations. I wonder if the latter will ever be practical with C 

[tggzzz]

<omitted points that I agree with>
I'm highly suspicious of people who use the term "syntactic sugar". They are usually people writing obtuse code, badly laid out on the page, which is easily screwed up by the odd misplaced bracket that is hard to count your way through and check. Syntax means little to a machine, but is means a HUGE amount to a developer trying to keep things clear.

In any sane language, wrong syntax leads to a compilation failure.

The counter example to your point is that too often people claim that new language features are a great advance, when all they manage to do is save a little typing. That's syntactic sugar. I think Java is tending to get to that stage with some of its newer language features.

OTOH different semantic structures mean you can express new concepts, and ways of solving problems, and ways of avoiding problems. Adding semantic structures to an existing language usually fails: it is better to either encapsulate the benefts in a library, or use a different language built around the concepts.

As for misplaced brackets, that doesn't occur with Java. All you have to do is invoke the IDE's "pretty print" operation (on code that compiles), and misplaced brackets are instantly visible in the indentation. Java also allows you to highlight a block of code, and invoke "convert to method"; the IDE automatically refactors the code, pulling out any method arguments that are required.

Those operations are foolproof in Java and impossible in C/C++, due to the crappy syntax and pre-processor.

Don't get me started on the modern fashion where indentation indicates nesting. Good luch pretty printing that!

[tggzzz]

I don't think it matters who created Rust, but the more languages they knew the better. The more languages the higher the probability they will extract the good bits and avoid the bad bits. That was very clearly demonstrated in Gosling's 1996 Java whitepaper.

If Rust was only a "simple safe subset" of C++, that would be a beneficial step. Rust adds extra novel capabilities on the form of ownership and non-mutability. That is absolutely vital with today's multicore processors and MCUs. C/C++ is painfully inadequate for those.

I never said it's simple and it isn't. Maybe simpler than C++ by the looks of it, but that's not saying much and it isn't worth much unless you are migrating from C++ rather than C. My recollection of reading their documentation and tutorials was "lots of language features, lots of jargon, lots of cryptic syntax" and you won't get far without being familiar with it all because the features are tangled with each other and widely used. Deciphering Rust code made me feel like I'm reading STL headers.

I haven't had occasion to use Rust, unfortunately.

Rust introduces new and valuable concepts and capabilities that should lead to good code well suited to modern machines. It is unsurprising that comes with new jargon and new syntax. Given the above caveat, the syntax and jargon doesn't strike me as any more challenging than equivalents in OOP languages, FSM languages, hardware description languages, statistics processing languages.

I'm happy if all the concepts have to be understood together, since that implies they are a coherant whole. The C++ alternative is an indiscriminate hodgepodge rammed together, leaving programmers to choose which subset they can use alongside the different subset used by other programmers.

Fundamentally new syntax is easy; you have to learn such every few years when a (worthwhile) new language comes along. New semantics are usually harder to get your head around.

The part about knowing other languages and extracting good bits from them is actually ironic, because what I forgot previously is that Rust designers were apparently ML fanboys too as the language borrows a bunch of syntax from there. ML has generics, but Rust chose templates and code generation as the answer to everything.

My impression is that it's at best a "sidegrade" from C. May fix some problems, will create others.

I've never bothered with ML or any of its many derivatives; they've never matched my objectives and constraints. I have no strong opinion about ML, either for or against.

In some senses yes it is a "sidegrade", e.g. still procedural (not OOP, FSM etc). In some senses no, e.g. built-in multiprocessing and memory safety.

Being a "sidegrade" is beneficial: it forces people into new (hopefully better) ways of thinking, rather than toddling along the the old way in an old language.

The potential attraction of Rust to me is it being easier and more reliable to produce efficient safer faster object code than with C/C++.

[tggzzz]

No idea.

I agree; you don't have any idea.

[aeberbach]

I worked (recently) with a guy who insisted on no comments because "code should be self documenting". Ignores the fact that months later when you come back to it, it is a lot quicker to read a succinct comment than to read the code and understand it in the context of everything it interacts with.

[coppice]

As for misplaced brackets, that doesn't occur with Java. All you have to do is invoke the IDE's "pretty print" operation (on code that compiles), and misplaced brackets are instantly visible in the indentation. Java also allows you to highlight a block of code, and invoke "convert to method"; the IDE automatically refactors the code, pulling out any method arguments that are required.

People are much too creative in misplacing bracket for that to catch a lot of errors.

[coppice]

I worked (recently) with a guy who insisted on no comments because "code should be self documenting". Ignores the fact that months later when you come back to it, it is a lot quicker to read a succinct comment than to read the code and understand it in the context of everything it interacts with.

On first release a good percentage of the comments don't say what the code does, due to poorly written comments, and things that changed during development. After 5 years of further development the comments and code are usually like elements of completely different projects. Comments aren't compiled, so there is no checking on their validity. If you are relying on comments, rather than using them to fill in gaps in understanding as a you read confusing bits of the code, you are not usually going to get very far.

A corollary which offers excellent results is something which got a lot of momentum in the late 80s, and faded away for political reasons. You use a tool to simulate what the product should do. You get the specifiers to work with the model, and find where its results agree and disagree with the model, and where the model has shown them their own thinking was woolly. You then correct the model to be in line with expectations. Rinse and repeat until everyone agree you have an accurate model. Now that model is a great document of the requirement. You develop production code, checking it against the model. When it agrees with the model there is an excellent chance it does exactly what it required.... as long as the model was thorough. I experienced things being handled in this way internally, but I am not aware of anyone ever signing off on a model like this as a specification between supplier and customer. As management realised they had a thorough, and near water tight, spec, they panicked at the lack of wiggle room, and insisted the formal spec between the two parties be the traditional woolly descriptive document.

[tggzzz]

As for misplaced brackets, that doesn't occur with Java. All you have to do is invoke the IDE's "pretty print" operation (on code that compiles), and misplaced brackets are instantly visible in the indentation. Java also allows you to highlight a block of code, and invoke "convert to method"; the IDE automatically refactors the code, pulling out any method arguments that are required.

People are much too creative in misplacing bracket for that to catch a lot of errors.

I don't think that can happen in Java. The nearest would be an omitted pair of brackets altering the intent, but overturning would reveal that as unwanted/unexpected indentation.

Parentheses are more problematic, with Java having marginally better syntax in that respect.

[tggzzz]

A corollary which offers excellent results is something which got a lot of momentum in the late 80s, and faded away for political reasons. You use a tool to simulate what the product should do. You get the specifiers to work with the model, and find where its results agree and disagree with the model, and where the model has shown them their own thinking was woolly. You then correct the model to be in line with expectations. Rinse and repeat until everyone agree you have an accurate model. Now that model is a great document of the requirement. You develop production code, checking it against the model. When it agrees with the model there is an excellent chance it does exactly what it required.... as long as the model was thorough. I experienced things being handled in this way internally, but I am not aware of anyone ever signing off on a model like this as a specification between supplier and customer. As management realised they had a thorough, and near water tight, spec, they panicked at the lack of wiggle room, and insisted the formal spec between the two parties be the traditional woolly descriptive document.

There are at least two technical concerns with that.

Firstly, as the saying goes, "all models are wrong, but some are useful". Without an accompanying set of comments about the model, the useless and incorrect attributes can become enshrined in the application.

Secondly, it is unlikely that any model will incorporate important aspects of the application's behaviour, e.g. ACID properties, high availability properties.

Yes, such things are also the downfall of overzealous belief in TDD.

[aeberbach]

The full-on model/test jig approach only works if time and budget are not your main concerns (or even a concern at all), and if comments can be poor, or things can change during development, that goes double for a model.

[coppice]

A corollary which offers excellent results is something which got a lot of momentum in the late 80s, and faded away for political reasons. You use a tool to simulate what the product should do. You get the specifiers to work with the model, and find where its results agree and disagree with the model, and where the model has shown them their own thinking was woolly. You then correct the model to be in line with expectations. Rinse and repeat until everyone agree you have an accurate model. Now that model is a great document of the requirement. You develop production code, checking it against the model. When it agrees with the model there is an excellent chance it does exactly what it required.... as long as the model was thorough. I experienced things being handled in this way internally, but I am not aware of anyone ever signing off on a model like this as a specification between supplier and customer. As management realised they had a thorough, and near water tight, spec, they panicked at the lack of wiggle room, and insisted the formal spec between the two parties be the traditional woolly descriptive document.

There are at least two technical concerns with that.

Firstly, as the saying goes, "all models are wrong, but some are useful". Without an accompanying set of comments about the model, the useless and incorrect attributes can become enshrined in the application.

Secondly, it is unlikely that any model will incorporate important aspects of the application's behaviour, e.g. ACID properties, high availability properties.

Yes, such things are also the downfall of overzealous belief in TDD.

I've been involved in projects where model driven specification was used and they are the only things I've ever done where the spec really tied things down at all well. Its not perfect, but its far ahead of anything else I've seen close up.

TDD is such a stupid concept. If you aren't testing extensively as you build things, for a variety of reasons, you are a moron, and if you think testing as you go is a profound new paradigm you are also a moron. The software business is a religion, constantly looking for its next guru to worship.

[coppice]

As for misplaced brackets, that doesn't occur with Java. All you have to do is invoke the IDE's "pretty print" operation (on code that compiles), and misplaced brackets are instantly visible in the indentation. Java also allows you to highlight a block of code, and invoke "convert to method"; the IDE automatically refactors the code, pulling out any method arguments that are required.

People are much too creative in misplacing bracket for that to catch a lot of errors.

I don't think that can happen in Java. The nearest would be an omitted pair of brackets altering the intent, but overturning would reveal that as unwanted/unexpected indentation.

Parentheses are more problematic, with Java having marginally better syntax in that respect.

What's the difference between parentheses and brackets? They are synonyms. Most modern languages use all three types in the ASCII character set.

[tggzzz]

A corollary which offers excellent results is something which got a lot of momentum in the late 80s, and faded away for political reasons. You use a tool to simulate what the product should do. You get the specifiers to work with the model, and find where its results agree and disagree with the model, and where the model has shown them their own thinking was woolly. You then correct the model to be in line with expectations. Rinse and repeat until everyone agree you have an accurate model. Now that model is a great document of the requirement. You develop production code, checking it against the model. When it agrees with the model there is an excellent chance it does exactly what it required.... as long as the model was thorough. I experienced things being handled in this way internally, but I am not aware of anyone ever signing off on a model like this as a specification between supplier and customer. As management realised they had a thorough, and near water tight, spec, they panicked at the lack of wiggle room, and insisted the formal spec between the two parties be the traditional woolly descriptive document.

There are at least two technical concerns with that.

Firstly, as the saying goes, "all models are wrong, but some are useful". Without an accompanying set of comments about the model, the useless and incorrect attributes can become enshrined in the application.

Secondly, it is unlikely that any model will incorporate important aspects of the application's behaviour, e.g. ACID properties, high availability properties.

Yes, such things are also the downfall of overzealous belief in TDD.

I've been involved in projects where model driven specification was used and they are the only things I've ever done where the spec really tied things down at all well. Its not perfect, but its far ahead of anything else I've seen close up.

TDD is such a stupid concept. If you aren't testing extensively as you build things, for a variety of reasons, you are a moron, and if you think testing as you go is a profound new paradigm you are also a moron. The software business is a religion, constantly looking for its next guru to worship.

Agreed.

There can be some places where TDD is beneficial, but they are limited to where the incremental functionality is directly related to the specification, and where there is a good specification. They fail completely for the <ugh> "non-functional requirements" </ugh> such as reliability, performance, availability, etc.

[tggzzz]

As for misplaced brackets, that doesn't occur with Java. All you have to do is invoke the IDE's "pretty print" operation (on code that compiles), and misplaced brackets are instantly visible in the indentation. Java also allows you to highlight a block of code, and invoke "convert to method"; the IDE automatically refactors the code, pulling out any method arguments that are required.

People are much too creative in misplacing bracket for that to catch a lot of errors.

I don't think that can happen in Java. The nearest would be an omitted pair of brackets altering the intent, but overturning would reveal that as unwanted/unexpected indentation.

Parentheses are more problematic, with Java having marginally better syntax in that respect.

What's the difference between parentheses and brackets? They are synonyms. Most modern languages use all three types in the ASCII character set.

(parentheses)
[brackets]
{braces}
https://practicaltypography.com/parentheses-brackets-and-braces.html

However there are different terms in English and American English, and some parts of the computer industry habitually use terminology lazily
https://en.wikipedia.org/wiki/Bracket

(And we'll skip over that I confused brackets and braces )

[coppice]

As for misplaced brackets, that doesn't occur with Java. All you have to do is invoke the IDE's "pretty print" operation (on code that compiles), and misplaced brackets are instantly visible in the indentation. Java also allows you to highlight a block of code, and invoke "convert to method"; the IDE automatically refactors the code, pulling out any method arguments that are required.

People are much too creative in misplacing bracket for that to catch a lot of errors.

I don't think that can happen in Java. The nearest would be an omitted pair of brackets altering the intent, but overturning would reveal that as unwanted/unexpected indentation.

Parentheses are more problematic, with Java having marginally better syntax in that respect.

What's the difference between parentheses and brackets? They are synonyms. Most modern languages use all three types in the ASCII character set.

(parentheses)
[brackets]
{braces}
https://practicaltypography.com/parentheses-brackets-and-braces.html

However there are different terms in English and American English, and some parts of the computer industry habitually use terminology lazily
https://en.wikipedia.org/wiki/Bracket

(And we'll skip over that I confused brackets and braces )

You can find some partisan somewhere on the internet to support pretty much any position. I can counter with https://shahadmahmud.medium.com/checking-parentheses-balance-using-stack-ce939faca1c3 after just 10s searching with Google.

[Siwastaja]

I worked (recently) with a guy who insisted on no comments because "code should be self documenting".

This is not a joke - it is mostly true. The opposite point is, if you need a lot of comments sprinkled everywhere, that's a super alarming red flag of the code quality. You only need a few comments describing some oddities that couldn't be avoided, plus actual documentation of the big picture and intent of the module / strategies used - this documentation can be in form of comments.

But most of the code will and must be self-documenting. That's why we have variable names, many different loop constructs, functions, data structures, enumerations, and so on. The information goes there. Then the information is always in the same format; it adhering to standard is easy to check; it's formal. Sprinkling comments that describe what the code does is just duplicated information, is not enforced to be formal, cannot be automatically tested / regression tested like code can, and needs to be manually synchronized to match with the code.

If, by comments, you meant the "bigger picture" thing, then I apologize. But usually I hear ridiculing the "self-documenting code" from people who expect to see a lot of trivial comments to describe what an obfuscated piece of code does, ridiculous stuff like using weird, abbreviated variable names then explaining in a comment what the variable really is about.

Self-documenting code is the correct approach. It may need supplementation from comments and separate documents, but it should be the baseline, always.

[tggzzz]

As for misplaced brackets, that doesn't occur with Java. All you have to do is invoke the IDE's "pretty print" operation (on code that compiles), and misplaced brackets are instantly visible in the indentation. Java also allows you to highlight a block of code, and invoke "convert to method"; the IDE automatically refactors the code, pulling out any method arguments that are required.

People are much too creative in misplacing bracket for that to catch a lot of errors.

I don't think that can happen in Java. The nearest would be an omitted pair of brackets altering the intent, but overturning would reveal that as unwanted/unexpected indentation.

Parentheses are more problematic, with Java having marginally better syntax in that respect.

What's the difference between parentheses and brackets? They are synonyms. Most modern languages use all three types in the ASCII character set.

(parentheses)
[brackets]
{braces}
https://practicaltypography.com/parentheses-brackets-and-braces.html

However there are different terms in English and American English, and some parts of the computer industry habitually use terminology lazily
https://en.wikipedia.org/wiki/Bracket

(And we'll skip over that I confused brackets and braces )

You can find some partisan somewhere on the internet to support pretty much any position. I can counter with https://shahadmahmud.medium.com/checking-parentheses-balance-using-stack-ce939faca1c3 after just 10s searching with Google.

Well, you have demonstrated that, which isn't a difficult task. 

So let's refer to an authoratative paper dictionary, the Websters New International Dictionary (Unabridged). If you have another authoratative paper dictionary, let's see its definitions

The entry for "parenthesis" is short and to the point; see meaning 2a and 2b. (Plus meaning 2c shows "brace")



The entry for "bracket" (unsurprisingly) much much longer, so I haven't shown it all; see meaning 4a and 4b

[aeberbach]

Self-documenting code is a good aim, but a blanket ban on any and all comments is blanket wrong.

[Siwastaja]

a blanket ban on any and all comments is blanket wrong.

I don't think anyone has seriously suggested doing that.

[Picuino]

Reddit meme.

[magic]

An actual programmer would write "90% of all comments" and that would be clear enough for the audience.

It looks like my tech-illiterate father's jokes about computers

[SiliconWizard]

Just about brackets - the term alone is ambiguous, at least in programming, it's more like a category of symbols than a particular pair.
The usual (although i'm sure some would find something to say) naming in english is:
- Square brackets: [ ]
- Angled brackets: < >

As for the braces, { }, they are usually called "curly braces". And for parentheses, ( ), I don't think it's too confusing. Normally.

[tggzzz]

Humpty Dumpty had a small speech about words and their meanings

[Nominal Animal]

- Angled brackets: < >

Unicode Miscellaneous Technical block contains 〈 (U+2329 left-pointing angle bracket) and 〉 (U+232A right-pointing angle bracket).  It's the section that also contains stackable (vertically, in different rows) forms:
  ⎛ ⎞ ⎡ ⎤ ⎧ ⎫ ⌠ ⎲ ⎰ ⎱
  ⎜ ⎟ ⎢ ⎥ ⎨ ⎬ ⎮ ⎳ ⎱ ⎰
  ⎝ ⎠ ⎣ ⎦ ⎩ ⎭ ⌡
as well as some useful button characters:
  ⏯ ⏸ ⏹ ⏺ ⏭ ⏮ ⏩ ⏪ ⏫ ⏬
Unicode Dingbats block does contain angle bracket ornaments in various thicknesses, too: ❬ ❭ ❮ ❯ ❰ ❱.
Unicode Miscellaneous Mathematical Symbols-A block contains ⟨ ⟩ ⟪ ⟫, and ⟦⟧ as Mathematical white square brackets, and ⟮ ⟯ as flattened parentheses.
Unicode Miscellaneous Mathematical Symbols-B block contains ⧼ ⧽ as curved angle brackets.
Unicode CJK Symbols and Punctuation has its own 〈 〉《 》.
The Basic Latin block (ASCII-compatible subset) has < (less-than) and > (greater-than), calls ( and ) parentheses, [ and ] square brackets, and { and } curly brackets.

(Note that wide ncurses (link against ncursesw) can use the above effectively even on terminals, pseudoterminals, and consoles, on Linux, Mac OS, BSDs; I'm only unsure about Windows and WSL, since traditionally Windows has required MS extensions to be used to read or write UTF-8 on the terminal console.  I do know PuTTY can handle those including colors and other ANSI escape codes in Windows when connecting to Linux/BSD/MacOS, if correct connection settings are used.)

I don't care much what people call each symbol or glyph (I'm fully aware of the differences), as long as they're consistent, and when asked, can refer to Unicode code points that correspond to what they mean, so I can use them in practice.


I've found Box Drawing and Block Elements Unicode blocks (list) extremely useful in code comments describing a table, graph, or simple curve, describing the behaviour of a function and why a specific approach was chosen in an intuitive manner, guiding any maintainer or code examiner a practical idea of what the code should accomplish.  These only really work with fixed-width (monospace) characters, and I wish there was a comment style, say //|, that told common editors to use a fixed-width font for the contents of that comment.  That would allow mixing normal text and such graphics in comments.  (I personally tend to use fixed-width fonts for source code myself.)

For math stuff, formulae and such, Arrows, Mathematical Operators, and Superscripts and Subscripts (and other related blocks) make it much easier to describe what a function or operation does in a mathematical manner.  For example, I believe "∑ A[i]·Cⁱ, 0 ≤ i ≤ n-1" is a better comment than say "A[0] + A[1]*C + A[1]*C**2 + ... + A[n-1]*C**(n-1)", because the former has less cognitive load than the latter.  Limiting oneself to Basic Latin, something like "sum(A[i]*C^i, i=0..n-1)" is a compromise, with less cognitive load to only those who are familiar with text-based Computer Algebra Systems that use a similar syntax.

Other Unicode blocks contain useful glyphs for drawing timing diagrams, etc. for electronics.

Because of this, while I only use Basic Latin Unicode block (i.e., printable ASCII plus newline plus Tab if already used in the sources) for the code itself (in C, C++, Python, Bash, etc.), I do like to use Unicode within comments, for the added expressibility.  This naturally means that I tend to use UTF-8 (without byte order mark, since it confuses pure-ASCII editors and utilities) for all my source code files.

(Using UTF-8 for source code, and non-ASCII characters only within comments, also means that you can write the correct form of peoples' names when needed.  I like being able to write "Bézier curve" and "Erdős–Szekeres conjecture, or happy ending problem" in a comment.)

Some like that, some dislike it, preferring to limit to Basic Latin ≃ ASCII, especially with C.  What grinds my gears is that browser developers have decided that UTF-8 is the only non-legacy character set, with the browser default character set having to be a legacy character set; i.e. that you should not be able to select UTF-8 as your default character set.  This means that if you open a file the browser considers a plain text file, and it contains aforementioned UTF-8 source code, the glyphs won't show up correctly by default; you have to fix or change the character encoding by hand for every new file displayed!
This annoys me to no end, because for the last two decades or so, all browser-displayable files (including plain text files like source code is) without an explicit browser-decipherable character encoding declared, have been in UTF-8.

[tggzzz]

Unfortunately quite a few of those don't render on my tablet

For the others, would it be possible to link to the specific plane, not just https://en.wikipedia.org/wiki/Plane_(Unicode)

[Nominal Animal]

Unfortunately quite a few of those don't render on my tablet

That is determined by the font you use: not all fonts have a good glyph coverage.  CJK may be poorly supported, for example.

The default font for normal text for this forum is Verdana, which has medium coverage; the default font for the teletype text ([tt]...[/tt])  is DejaVu Sans Mono, or if that is not installed, Monaco, and so on.  I recommend you consider installing the full font (from DejaVu Fonts github; it is a free font), as the WebFont versions tend to be limited to a subset of glyphs, but the DejaVu Sans Mono font itself has pretty good coverage (coverage in PDF form).

It is not just for this site either, because it is a common font with a nice coverage; if you install the other DejaVu Sans variants, you can set it as your default Sans Serif font in your browser, so pages like Wikipedia will have a nice glyph coverage.  And it should look nice, too.

For the others, would it be possible to link to the specific plane, not just https://en.wikipedia.org/wiki/Plane_(Unicode)

I added the links to the correct blocks I mentioned, and consolidated the two links to that to a single link ("list").

[tggzzz]

installing fonts is a never-ending rathole. Think IBM Selectric golf balls

This runs straight into the dilemma of whether something should be displayed in a manner determined by the viewing device or determined by the author.

The former is is good where the author wants to get content and information into the readers forebrain. The latter is good where the author wants to get pixels and emotion into the top readers hindbrain.

Too much of the web is the latter.

[Nominal Animal]

installing fonts is a never-ending rathole.

Not really.  Linux users will want to install MS Core Fonts or fonts-liberation2; and fonts-dejavu-core, fonts-dejavu-extra, fonts-freefont-ttf, fonts-noto-mono, fonts-noto-ui-core, fonts-noto-cjk, fonts-noto-color-emoji, fonts-opensymbol, fonts-mathjax, plus whatever the distribution installs.

fonts-noto-* refers to the No Tofu font, at https://fonts.google.com/noto, which has extremely wide Unicode coverage.
DejaVu fonts are free fonts similar to Bitstream Vera (sans) and Bitstream Charter (serif), with very wide Unicode coverage.
GNU FreeFont (FreeMono, FreeSans, FreeSerif) are free fonts with as wide Unicode coverage as possible.
OpenSymbol fonts are used in many text documents' ornaments (in default templates for greeting cards and such), and the fonts-mathjax font package ensures one can render MathJax correctly locally (with just the JavaScript files) without an internet connection, as normally MathJax uses WebFonts.

So, I'm only recommending one installs No Tofu, DejaVu, and FreeFont.  Of these, only DejaVu is widely used, so that alone suffices; the others are optional and for variety.  As I already said, DejaVu Mono is already used for teletype text on this forum (and many other SMF forums); and if you set your browser monospace, serif, and sans serif default character sets to NoTo/DejaVu/FreeFont (whichever pleases you most), you won't see the annoying boxes instead of the correct glyphs anymore!

(For text such as this one, the preferred font order is Verdana, Arial, Helvetica, sans-serif.  Note that Verdana is metrically compatible with DejaVu Sans, having the same size glyphs.)


The way CSS specifies a font includes three generic names: "serif", "sans-serif", and "monospace".  These are generic font names, for the express purpose of using whatever font the user desires for serif/no-serif and monospace text.  Your browser will let you select these.  By default, they often default to the similar operating system defaults set by your UI theme.  However, many OS fonts have poor Unicode coverage, which leads to *some* glyphs missing (or replaced with boxes).  To avoid this in your browser, it is quite important to set those three default fonts to a font you like, with the correct properties, and with a wide Unicode coverage.

A lot of web pages do not specify a specific font, only the generic font.  (Even when they do specify one, they usually specify a list of preferred fonts in order of preference, which is terminated with one of the three generic names.)  A good example of this is Wikipedia: both the current and the previous default skins use "sans-serif" for the body text.  Thus, whether you see all glyphs in Wikipedia pages or not, depends on what you have set for the above three default ones in your browser, or what they default to if you haven't touched them at all.

If you open plain text files in your browser, either locally or via HTTP or HTTPS with mime type text/plain, your browser will use the "monospace" default font you have set.

I do not recommend adding many fonts to ones system, just DejaVu, and optionally NoTo and/or FreeFont, depending on what you yourself prefer.  DejaVu is commonly used on the web, and covers Unicode quite well, so it is a good choice for a default font in your browser.  If you don't like it that much, pick NoTo or FreeFont instead for your browser default fonts.  (I often use DejaVu Sans and DejaVu Serif for text, but a different one for monospace, because DejaVu Sans Mono is too large compared to the other two, and just using a smaller point size leads to Unicode Block Elements to no longer connect when mixed with DejaVu Sans or Serif text on the same line.)

[Nominal Animal]

I do use, and want to use, UTF-8 (and selected Unicode blocks) in comments, because they should convey the information with minimum cognitive load, and I personally do need UTF-8 to do that.

For the same reason as browsers allow users to set a default font for serif/sans-serif/monospace, I do believe it would be useful to have a "standardized" comment form that will be rendered in a separately-selectable monospace font with wide Unicode coverage.  I fully understand tggzz's font worries above, but often the most comfortable character set for code in your code editor does not have good Unicode coverage at all.  This is exactly where my suggestion about a standard Unicode comment form would be particularly useful: it would allow programmers to use their preferred Basic Latin or ASCII font for code and comments, but a wider-coverage font for Unicode comments.

Technically, U+002F U+002F U+2003 or "// ", the third character being em-space, would be near-perfect, except it is very hard to type.

This is why I suggested "//|" for C and C++ for exactly this, as it is easy to type, and is somewhat aligned with existing practices, and should be easy to add to existing editors.

It does not affect me personally that much, because I use UTF-8 Everywhere, and a monospace font (NoTo/DejaVu Mono/FreeMono) with wide Unicode coverage for my source code and plain-text documentation files.

I just wanted to show how using Unicode (especially for math expressions) via UTF-8 can yield better code comments, and maybe spark some ideas (and hear any objections) others have related to that.  I do know some people really don't like UTF-8.


I do strenuously reject comments that refer to documentation, except for naming a specific documentation file.  For math-heavy projects, this leads to documentation being split into multiple files.

(As an aside: what file format to use for rich text? HTML+CSS+JS works in a browser even locally, but is annoying to edit.  LaTeX and word processing formats save horrible HTML, but quite nice PDF files.  LaTeX, TeX, and MathJax and various markup languages, can produce very nice output in various formats, but one needs those document authoring tools installed to edit the documentation, and if it takes too much time/effort, it will not get done.)

I personally do like plain text files with UTF-8 for documentation (except LibreOffice + Math for reference book style math with proofs, or LaTeX for physics), assuming the file is displayed with a monospace font that covers at least Unicode blocks
Latin 1 Supplement (Ä, ö, é, ç, ×, ÷, ·, µ, ±, °),
General Punctuation (non-breaking space, ' ' aka em-space for graphics, ―, –),
Greek and Coptic (π, φ, ω, λ, β, etc.),
Box Drawing (┤,╦, ╱, ╲, ╳, etc.),
Block Elements (▘, ▞, ▙, █, ▓, ▒, ░, etc.),
Arrows (←, ↑, →, ↓, ↔, ↕, ⇐, ⇒, ⇔, etc.),
Mathematical Operators (≃, ≈, ≠, ≡, ≢, ≤, ≥, ∂, ∑, ∏, ∫, ⊕, ⊖, ⊗, ⊘, ⊙, ⊚, ⊛, ⊜, ⊝),
and ballots (☐, ☑, ☒) from Miscellaneous Symbols.
Enclosed Alphanumerics can be very useful for dense (single-character) 2D matrices or tables with 20 (numbers ①, ②, ‥, ⑲, ⑳; ⑴, ⑵, ‥, ⒆, ⒇; ⒈, ⒉, ‥, ⒚, ⒛) or 26 (uppercase letters Ⓐ, Ⓑ, ‥, Ⓩ) single-character elements; the enclosed lower-case letters (ⓐ, ⓑ, ‥, ⓩ) are often not very legible.

Within code comments, the set I need is basically the same, except for Block Elements, Miscellaneous Symbols, and Enclosed Alphanumerics.  (In documentation, Block Elements contains the 15 glyphs needed (+ space) to display 2×2 graphics, so it can be useful for dense boolean or binary 2D matrices.  Other than those, they're often used for banners.)

[coppice]

That is determined by the font you use: not all fonts have a good glyph coverage.  CJK may be poorly supported, for example.

These days CJK coverage is usually fine. Its technical things that have the most issues. The symbols coverage for maths, logic, and related things can still be pretty patchy. I usually view technical PDFs in Firefox or Chrome these days. They seem to display everything well.

[Nominal Animal]

That is determined by the font you use: not all fonts have a good glyph coverage.  CJK may be poorly supported, for example.

These days CJK coverage is usually fine. Its technical things that have the most issues. The symbols coverage for maths, logic, and related things can still be pretty patchy. I usually view technical PDFs in Firefox or Chrome these days. They seem to display everything well.

PDF files typically include the vector description of the glyphs it uses, similar to how browsers can use WebFonts.

The interesting thing here is that for HTML files, including this forum, one can trivially add webfonts, as long as one has a suitable license.

For teletype text ([tt]...[/tt] and code blocks), the DejaVu Sans Mono font is used on this forum, with Monaco (an Apple Mac font) as a backup.  As DejaVu Sans is licensed under a free license that basically requires you only to provide the license file with the font typeface, it would be trivial to add to this forum as a web font!

Indeed, I created a self-explanatory example of this here, with a PDF version of the same page, for anyone to take a look at how that would work. Because I'm only interested in the monospace font, the entire page uses the monospace font as shown.
(Note that when aligning Box Drawing or Block Element characters on different lines, you need to use em-space (U+2003, ' ') or pairs of half-em/en-space (U+2002, ' ') instead of normal spaces for alignment! You only use normal space for aligning Latin characters and such.)

While this is veering a bit too far away from code comments, this is related to documentation (when using Markdown/MathJax/Sphinx etc. generators to generate HTML and/or PDF documentation from plain text markup files).  One can use FontForge (free and open source) to edit TrueType and OpenType fonts, and generate WOFF 1.0 format WebFonts from them.  (For WOFF2, I use fonttools, specifically python3 fontTools/ttLib/woff2.py compress -o fontname.woff2 fontname.ttf)
Remember: WebFonts are not installed, just referred to via CSS, and the browser will use those just as if it was actually installed locally.

FontForge is also useful when you have a preferred source code editing font, but with some niggle (perhaps O 0 or I 1 l are too similar): you can create your custom variant from the original TrueType/OpenType font, by just renaming it, and editing the niggles to better suit your needs.  Just remember to install the modified version of the TrueType/OpenType font after each edit, and that the renamed font is used in your editor.

[PlainName]

As DejaVu Sans is licensed under a free license that basically requires you only to provide the license file with the font typeface

How would one do that for such as a web page? Or is the intent to make the license available on request rather than provide (with the implication of 'with')?

[Nominal Animal]

As DejaVu Sans is licensed under a free license that basically requires you only to provide the license file with the font typeface

How would one do that for such as a web page? Or is the intent to make the license available on request rather than provide (with the implication of 'with')?

Generally, as with similar BSD and MIT licenses, it suffices that it is obvious for anyone looking at the sources (or documentation, but web pages obviously don't have documentation).

In the case of my example page, the note pointing to the license file is exactly where you discover the web font URL when looking at the HTML/CSS source files, as a CSS comment; with the license file itself copied next to the font files (i.e, on this same server, not on some upstream server).  This should best fulfill the intent of the license.

(Of course, I am assuming that if you intend to use those on your own web pages, either local or a server, you'll copy the files, instead of linking to those on my server.  It's just four files, for a total of under one megabyte, a third of which is the original TrueType font file.  The same procedure would be repeated for any other free fonts licensed using a similar license.  Typically, a web site or pages should not need more than three fonts, plus optionally MathJax web fonts.)

[PlainName]

Thanks.

Completely unrelated:

for a total of under one megabyte

I remember when that was unimaginably big. Nowadays, 1GB is the new MB, although even that doesn't seem so terrible to transfer.

Merry Xmas   

[coppice]

PDF files typically include the vector description of the glyphs it uses, similar to how browsers can use WebFonts.

PDFs can include vector descriptions, but rarely do. 90% or more of the technical documents I use do not display correctly unless I use a platform with comprehensive font coverage, like Chrome or Firefox. For example, I have never seen an ITU document which displays correctly without adequate symbol coverage in the platform.

[Nominal Animal]

PDF files typically include the vector description of the glyphs it uses, similar to how browsers can use WebFonts.

PDFs can include vector descriptions, but rarely do. 90% or more of the technical documents I use do not display correctly unless I use a platform with comprehensive font coverage, like Chrome or Firefox. For example, I have never seen an ITU document which displays correctly without adequate symbol coverage in the platform.

When the generation is via PostScript, the PS-to-PDF conversion often assumes the core PostScript fonts are installed.  This leads to PDF files that refer to PostScript Core Fonts without including them, leading to PDF files that require those fonts to be included for the PDF to render correctly.  This is typical for large organizations which "moved" to PDF by just appending a PS-to-PDF conversion to their existing PostScript format publishing systems.

I checked the PDF version of the example DejaVu Sans Mono webfont example HTML page I created, and I verified with FontForge (it can extract fonts from PDF files) that it did include the used glyphs from the DejaVu Sans Mono font in it.  Basically all PDF files I create do include the glyph definitions for all characters used in that document, so I do object a bit about that "but they rarely do [include the font typefaces used in it]".

If we adjust the statement to "PostScript-oriented and MS Windows -based PDF generation often omits default fonts used in Windows or defined as PS Core Fonts, leading to PDF files with missing fonts on other systems", then I do agree.


The point is that one should not assume that generating a PostScript file and then converting that to PDF yields optimal results, because it does not.  One should always use the "native" 'export to PDF' or 'print to PDF file' approach instead.

[coppice]

PDF files typically include the vector description of the glyphs it uses, similar to how browsers can use WebFonts.

PDFs can include vector descriptions, but rarely do. 90% or more of the technical documents I use do not display correctly unless I use a platform with comprehensive font coverage, like Chrome or Firefox. For example, I have never seen an ITU document which displays correctly without adequate symbol coverage in the platform.

When the generation is via PostScript, the PS-to-PDF conversion often assumes the core PostScript fonts are installed.  This leads to PDF files that refer to PostScript Core Fonts without including them, leading to PDF files that require those fonts to be included for the PDF to render correctly.  This is typical for large organizations which "moved" to PDF by just appending a PS-to-PDF conversion to their existing PostScript format publishing systems.

I checked the PDF version of the example DejaVu Sans Mono webfont example HTML page I created, and I verified with FontForge (it can extract fonts from PDF files) that it did include the used glyphs from the DejaVu Sans Mono font in it.  Basically all PDF files I create do include the glyph definitions for all characters used in that document, so I do object a bit about that "but they rarely do [include the font typefaces used in it]".

If we adjust the statement to "PostScript-oriented and MS Windows -based PDF generation often omits default fonts used in Windows or defined as PS Core Fonts, leading to PDF files with missing fonts on other systems", then I do agree.


The point is that one should not assume that generating a PostScript file and then converting that to PDF yields optimal results, because it does not.  One should always use the "native" 'export to PDF' or 'print to PDF file' approach instead.

Yes, I think most people here know most of this, but it is completely irrelevant. The reality is most of the technical PDFs you get need full character set support in the display platform, and its still uncommon to have that, unless you use Firefox or Chrome (and probably Apple's alternatives). I haven't seen a Linux platform where Okular, Evince or other tools display properly, as they all rely on the system's font set, and by default its quite lacking. There is a reason why Firefox and Chrome on Linux machines sorts fonts out for itself. Try Acrobat on Windows. It will generally detect that some glyphs are not available and trigger the installation of additional fonts, but it can be quirky, and still leave you with unrendered stuff.

[Nominal Animal]

I haven't seen a Linux platform where Okular, Evince or other tools display properly, as they all rely on the system's font set

NOT TRUE!  They use the embedded glyphs, if available.  For proof, open the attached xnib.pdf PDF file in any of them.

I used FontForge to modify the letter x in the DejaVu Sans Mono font to have a small extra nib/serif in the upper left, and generated a WebFont from that.
(Note that after generating the webfont files (xnib.woff2 and xnib.woff), I completely deleted the modified TrueType font.  It was never installed on my system, and only exists as a Web Font at this point.)
I then reused my existing example HTML page, changing the CSS reference to xnib2.woff2 and xnib.woff only, and replaced the text with a single x.
In Firefox, that page when opened, shows the extra nib/serif in that x.  I then saved that page as xnib.pdf, as attached.

If you open the PDF a browser, you'll see an A4 portrait sized page, with a gray rectangular outline, with a single x near the upper left corner –– with that extra nib/serif in that x.

If you open the PDF file in any of the programs you mentioned, if you see an x with a nib/serif, the viewer uses the embedded font/glyph/typeface in the PDF, contrary to what you asserted.
Only if you see a normal monospace x, does the viewer use a system font.

In all PDF viewers I have in Linux Mint 20.3, including Evince, I see the nib; they thus use the embedded glyph, and not the system font.

Note that you can still copy the letter x from the PDF when viewing it, and it will paste as a normal letter x.  It is not graphic; it is text, just with a custom typeface (glyph for x).

I assert that the font problem is because people generate the PDF files wrong!

In Windows, you have to do some deep configuration in the PDF-emitting programs/drivers to get it to embed the fonts that are installed by default on Windows, because Microsoft only considers people using Windows, and prefers things looking shitty on all other systems.  Similarly on Mac OS wrt. standard Apple fonts.  Similarly, any document generation path that first generates PostScript, will assume that PostScript Core Fonts are installed, and when such a file is converted to PDF, those PS Core Fonts are assumed to be installed in all viewers and are not embedded in the PDF file.

I am very, very serious about this, and the attached xnib.pdf is my immediate proof proving your assertion (that Linux viewers like Evince and Ocular use system fonts and not the embedded glyphs in the PDF) is absolutely incorrect, in a form that is easily verifiable.


If you find it hard to accept my reasoning above, just let me know, and I'll create a second example HTML page, this time with a customized (extended) font, and instructions on how it (and the PDF version of that HTML page) was created, so you can reproduce everything for yourself, and verify this all for yourself.
I do expect you to then try and reproduce it, and report back, however.  Tit for tat!

In particular, it is not necessary to include the TrueType font file in the CSS; the WOFF2 and WOFF formats will suffice for all current and non-ancient browser versions (Firefox 3.6 and later, Chrome 6.0 and later, IE 9 and later, Konqueror since KDE 4.4.1, MS Edge (all versions), Opera 11.10 and later (Presto 2.7.81 and later), Safari 5.1, webKit build 528 and later).  Including the TTF font is just a nicety, that may help future browsers; plus, if installed (and only the TrueType/OpenType version can be "installed"), it allows those editing the HTML to see the same glyphs in their editor, instead of only in the browser.  It does not matter for the nibbed x here, but it does matter with fonts having custom Private Use Area characters.

[coppice]

I haven't seen a Linux platform where Okular, Evince or other tools display properly, as they all rely on the system's font set

NOT TRUE!  They use the embedded glyphs, if available.  For proof, open the attached xnib.pdf PDF file in any of them.

I used FontForge to modify the letter x in the DejaVu Sans Mono font to have a small extra nib/serif in the upper left, and generated a WebFont from that.
(Note that after generating the webfont files (xnib.woff2 and xnib.woff), I completely deleted the modified TrueType font.  It was never installed on my system, and only exists as a Web Font at this point.)
I then reused my existing example HTML page, changing the CSS reference to xnib2.woff2 and xnib.woff only, and replaced the text with a single x.
In Firefox, that page when opened, shows the extra nib/serif in that x.  I then saved that page as xnib.pdf, as attached.

If you open the PDF a browser, you'll see an A4 portrait sized page, with a gray rectangular outline, with a single x near the upper left corner –– with that extra nib/serif in that x.

If you open the PDF file in any of the programs you mentioned, if you see an x with a nib/serif, the viewer uses the embedded font/glyph/typeface in the PDF, contrary to what you asserted.
Only if you see a normal monospace x, does the viewer use a system font.

In all PDF viewers I have in Linux Mint 20.3, including Evince, I see the nib; they thus use the embedded glyph, and not the system font.

Note that you can still copy the letter x from the PDF when viewing it, and it will paste as a normal letter x.  It is not graphic; it is text, just with a custom typeface (glyph for x).

I assert that the font problem is because people generate the PDF files wrong!

In Windows, you have to do some deep configuration in the PDF-emitting programs/drivers to get it to embed the fonts that are installed by default on Windows, because Microsoft only considers people using Windows, and prefers things looking shitty on all other systems.  Similarly on Mac OS wrt. standard Apple fonts.  Similarly, any document generation path that first generates PostScript, will assume that PostScript Core Fonts are installed, and when such a file is converted to PDF, those PS Core Fonts are assumed to be installed in all viewers and are not embedded in the PDF file.

I am very, very serious about this, and the attached xnib.pdf is my immediate proof proving your assertion (that Linux viewers like Evince and Ocular use system fonts and not the embedded glyphs in the PDF) is absolutely incorrect, in a form that is easily verifiable.


If you find it hard to accept my reasoning above, just let me know, and I'll create a second example HTML page, this time with a customized (extended) font, and instructions on how it (and the PDF version of that HTML page) was created, so you can reproduce everything for yourself, and verify this all for yourself.
I do expect you to then try and reproduce it, and report back, however.  Tit for tat!

In particular, it is not necessary to include the TrueType font file in the CSS; the WOFF2 and WOFF formats will suffice for all current and non-ancient browser versions (Firefox 3.6 and later, Chrome 6.0 and later, IE 9 and later, Konqueror since KDE 4.4.1, MS Edge (all versions), Opera 11.10 and later (Presto 2.7.81 and later), Safari 5.1, webKit build 528 and later).  Including the TTF font is just a nicety, that may help future browsers; plus, if installed (and only the TrueType/OpenType version can be "installed"), it allows those editing the HTML to see the same glyphs in their editor, instead of only in the browser.  It does not matter for the nibbed x here, but it does matter with fonts having custom Private Use Area characters.

Again, this is well known but irrelevant. We have to read the documents we are provided with. They hardly ever contain the glyph information. A simple clean install of any Linux distro I have tried - Fedora, Debian, Ubuntu - setups up system fonts with very little in the symbols area. Most PDF viewers use those fonts, and fail to display properly. So, I use Firefox or Chrome, which have very comprehensive font sets built in.

[Nominal Animal]

We have to read the documents to are provided with. They hardly ever contain the glyph information.

That will only change if we tell those providing the documents they are generating them wrong, and push them to do it right.

Just like with code comments, we can agree a lot of them are utter garbage, less than useful.
I'm saying that instead of stripping the code comments out or telling people not to use comments at all, we push those we can to write good/better, useful comments, and for them in turn to push others when they can.

We cannot affect everyone, neither developers or document providers.  We can only affect those who care about our feedback, like learners in my case.

Yet, if we don't push back at all, we're essentially just accepting that the world is filling with more and more shit, and doing nothing about it.
I don't think that is useful.  I think pushing back, where possible, and at minimum pointing at the true culprit, is the reasonable path.

The true culprits are wrong methods/tools/settings used to generate the documents; and bad choices of what to describe in code comments.

There is zero value in blaming the end result –– that most code comments end up being not useful; or noting how hard it is to get all the fonts installed in Linux that Windows/Mac/PostScript document generators' take for granted and assume are installed.

[coppice]

We have to read the documents to are provided with. They hardly ever contain the glyph information.

That will only change if we tell those providing the documents they are generating them wrong, and push them to do it right.

Just like with code comments, we can agree a lot of them are utter garbage, less than useful.
I'm saying that instead of stripping the code comments out or telling people not to use comments at all, we push those we can to write good/better, useful comments, and for them in turn to push others when they can.

We cannot affect everyone, neither developers or document providers.  We can only affect those who care about our feedback, like learners in my case.

Yet, if we don't push back at all, we're essentially just accepting that the world is filling with more and more shit, and doing nothing about it.
I don't think that is useful.  I think pushing back, where possible, and at minimum pointing at the true culprit, is the reasonable path.

The true culprits are wrong methods/tools/settings used to generate the documents; and bad choices of what to describe in code comments.

There is zero value in blaming the end result –– that most code comments end up being not useful; or noting how hard it is to get all the fonts installed in Linux that Windows/Mac/PostScript document generators' take for granted and assume are installed.

Why are they wrong? Stuffing glyphs into documents was supposed to be a temporary bodge during a trasitional period. It is, perhaps, a good long term way to deal with truly special characters, that are not part of the Unicode set, although it can create some issues with compare, sorting, and so on. After all these years we should be able to rely on a Unicode character set being complete on all but a very small platform. If I plug a USB stick into my car, and play songs, my UK model car shows the Chinese song titles properly, even for some of the more obscure Chinese characters. Its 30 years since I first worked with Unicode (which itself was a bodge from day 1, as MS got them to base it on 16 bit characters), and we are still dealing with these issues on shiny new systems. Its pathetic.

[Nominal Animal]

Why are they wrong? Stuffing glyphs into documents was supposed to be a temporary bodge during a trasitional period.

Says who?

As we see with WebFonts, it is the only way to get glyphs to look the same everywhere.  This is an uncontrovertible fact.
In the print industry prior to PDF and web fonts, you had to discuss the font selection with your printer.

After all these years we should be able to rely on a Unicode character set being complete on all but a very small platform. If I plug a USB stick into my car, and play songs, my UK model car shows the Chinese song titles properly, even for some of the more obscure Chinese characters. Its 30 years since I first worked with Unicode (which itself was a bodge from day 1, as MS got them to base it on 16 bit characters), and we are still dealing with these issues on shiny new systems. Its pathetic.

Such bodges were dropped in 1996, when Unicode 2.0 was introduced.  By that time, UTF-8 had also evolved to its final form, with one to four bytes per code point, covering U+0000 to U+10FFFF.  Just like C has evolved from the K&R times, Unicode and UTF-8 has as well.  Just because Microsoft decided to stay in the dark ages, does not mean everyone else has to suffer too.

Older fonts' typefaces were designed before the Unicode era, and thus all currently used glyphs were never designed for those typefaces/fonts.

DejaVu fonts (derived from the Bitstream Vera and Charter typefaces), GNU FreeFont (based on the Nimbus Sans/Serif/Mono fonts donated by URW++), and Noto / No Tofu (based on Droid Sans/Serif/Mono by the original Droid font designer) were explicitly designed to fix that.  They are all licensed under a free license that allows including them in applications and web pages (with very minor license-file related requirements).
(They also allow extending the font with new glyphs, although exact requirements then vary, but generally you need to use a completely different name, and use the same license as the parent font was licensed under.)

The problem is that not all authors choose to use such fonts, and web site and forum managers don't bother to provide them as web fonts.

Just like PDF authors don't bother to embed the glyphs used, and just assume everyone has the same OS and OS version, and thus fonts, they do.
In most current Linux distributions, if you print something to a PDF file, it will embed the glyphs to the PDF file, so that those files will look the same for everyone viewing the file regardless of what fonts they have installed on their system.

I consider it an error when anyone creates a PDF file that does not do the same.  It is like choosing one specific font to be used on your web page, laying it out exactly using that font, and then not caring a whit if the users have that font installed or just see a garbled web page.

[nctnico]

I consider it an error when anyone creates a PDF file that does not do the same.  It is like choosing one specific font to be used on your web page, laying it out exactly using that font, and then not caring a whit if the users have that font installed or just see a garbled web page.

On that subject: it would be really nice if font creators also care whether the fonts render well without needing anti-aliasing / font smoothing. Some websites are completely unreadable because the fonts don't render correctly without anti-aliasing.

[AntiProtonBoy]

Why does no-one write comments any more? Not even just something to say what the function is meant to do, never mind the intricacies of how it goes about that. Some cryptic 12-character name may mean something to the programmer but it's bugger-all use when coming afresh to get a birds-eye view of things.

And variables! Really, do babies die or something if you let on WTF a variable is about?

If you need comment your code extensively, it's either badly written code, or function names and variables are poorly chosen. Well structured code should be essentially self-documenting and its functionality be self evident. Function names are descriptive and variables label what they contain. Better still, type system constrains and tells you what the variable represents (like units of measure, etc). The problem with commenting code is that they are always out of date and tell you lies. The only time i find myself commenting code is to describe some unusual algorithm or mathematical concept, with citations/references included.

[PlainName]

If you need comment your code extensively, it's either badly written code, or function names and variables are poorly chosen

Yes, so best give up and do something else. Or, you could just add a comment to help out the viewer a bit. No-one is perfect, yet all we see here is the assumption that we must be. Or else... well, what?

I guess we don't need to mark on circuit diagrams what that block does, or note expected measurement ranges, or any of the nice stuff that make circuit diagrams great to use. The wires between pins says it all anyway, right?

Go on, allow for non-gurus to actually be able to figure your shit out. It doesn't make you any less brilliant (the reverse, in fact).

[AntiProtonBoy]

Yes, so best give up and do something else. Or, you could just add a comment to help out the viewer a bit. No-one is perfect, yet all we see here is the assumption that we must be. Or else... well, what?

Nobody says anything about giving up. It's about learning best practices. It literally takes zero effort to type extra characters that conveys a meaningful function name, or a variable name. I've seen way too many "helpful" comments that lead me to down to a garden path of misdirections, only because the code was re-factored a few years ago, leaving the comments unchanged and completely irrelevant.

[tggzzz]

Yes, so best give up and do something else. Or, you could just add a comment to help out the viewer a bit. No-one is perfect, yet all we see here is the assumption that we must be. Or else... well, what?

Nobody says anything about giving up. It's about learning best practices. It literally takes zero effort to type extra characters that conveys a meaningful function name, or a variable name. I've seen way too many "helpful" comments that lead me to down to a garden path of misdirections, only because the code was re-factored a few years ago, leaving the comments unchanged and completely irrelevant.

Ah, the "some comments are wrong therefore all comments are wrong" zealotry.

Names don't indicate why and why not. Names dont indicate why you don't have to look at and comprehend a big blob of code in the first place.

[AntiProtonBoy]

Spare me the reductionist strawmans mate. Read my previous comment here:
https://www.eevblog.com/forum/programming/comments/msg5241498/#msg5241498

The only time i find myself commenting code is to describe some unusual algorithm or mathematical concept, with citations/references included.

[tggzzz]

Spare me the reductionist strawmans mate. Read my previous comment here:
https://www.eevblog.com/forum/programming/comments/msg5241498/#msg5241498

The only time i find myself commenting code is to describe some unusual algorithm or mathematical concept, with citations/references included.

Given what you wrote in this thread, at least two people think my response was not a straw man response.

You have my apologies for not having committed all your writings to memory.

[PlainName]

It literally takes zero effort to type extra characters that conveys a meaningful function name, or a variable name.

It literally takes zero effort to type in a program. You are talking the mechanics, which is typically thought-free. What does take effort is the creative thinking: the design of what the things does, how the various parts interact, how it is partitioned, etc. And part of that is thinking up names that describe fully, yet succinctly, everything the variable or function is about. Not just right now as it comes into your head but indefinitely (because no-one is going to change it once it's made it past the first compile).

I've thought up some brilliant names during my time (albeit not to do with programming) and some of them took months. Yet you reckon that you and anybody worthy of the title 'programmer' can come up with endless perfect names on the spur of the moment.

No, that's armchair warrior thinking. And I bet none of you variable names would tell me why it is there and how it should be used.

[coppice]

Yes, so best give up and do something else. Or, you could just add a comment to help out the viewer a bit. No-one is perfect, yet all we see here is the assumption that we must be. Or else... well, what?

Nobody says anything about giving up. It's about learning best practices. It literally takes zero effort to type extra characters that conveys a meaningful function name, or a variable name. I've seen way too many "helpful" comments that lead me to down to a garden path of misdirections, only because the code was re-factored a few years ago, leaving the comments unchanged and completely irrelevant.

Ah, the "some comments are wrong therefore all comments are wrong" zealotry.

Names don't indicate why and why not. Names dont indicate why you don't have to look at and comprehend a big blob of code in the first place.

He didn't really say that. He said one of the points I have also made, based on studying lots of code over decades. After a few years of continuing development the comments rarely say anything meaningful about the details of the code as it is today. Its doesn't even take a major refactor. General development is enough. It seems to heavily relate to another point I have made, that comments are not compiled and so never checked. When people modify code they tend to avoid touching any comments, like they carry a plague. So, comments never event attempt to follow the develop of the code after its initial release. The only best practice I have found is never ever trust anything in a comment, but use them as a last resort when you are really puzzled by the code. They might tell you something about the code you have, but more likely will tell you something fairly distorted about what the code looked like in its early days. Knowing what the original author intended has given me an inportant clue more than once.

[madires]

If you don't like my comments simply don't read them!

[PlainName]

After a few years of continuing development the comments rarely say anything meaningful about the details of the code as it is today.

They are history and can say things that the words comprising them don't: just being wrong says a lot about the code. Of course, if one sets out thinking they are pointless then the subtle usefulness will never be noticed. Happens in all fields, that.

[tggzzz]

After a few years of continuing development the comments rarely say anything meaningful about the details of the code as it is today.

They are history and can say things that the words comprising them don't: just being wrong says a lot about the code. Of course, if one sets out thinking they are pointless then the subtle usefulness will never be noticed. Happens in all fields, that.

Or even the unsubtle necessities.

I've seen zealots ignore comments, and thereby destroy necessary properties and preconditions.

[coppice]

After a few years of continuing development the comments rarely say anything meaningful about the details of the code as it is today.

They are history and can say things that the words comprising them don't: just being wrong says a lot about the code. Of course, if one sets out thinking they are pointless then the subtle usefulness will never be noticed. Happens in all fields, that.

Its not uncommon to find routines where someone clearly took a working routine that had the right framework to it, and produced an entirely different routine by reworking the heart of it. When there are a group of routines which all need to have the same call and return structure, so they can be called indirectly, its very common to see this development behaviour, and it makes sense. It not only reduces typing, but it helps to keep the group of routines consistent. However, its also common to find the first routine was thoroughly commented, then all the others were produced by replacing the core of the code, with no changes to the comments. So, unless you spot the commonality between the group, the comments can seem truly bizarre.

[Nominal Animal]

On that subject: it would be really nice if font creators also care whether the fonts render well without needing anti-aliasing / font smoothing. Some websites are completely unreadable because the fonts don't render correctly without anti-aliasing.

Absolutely true.

The Web Open Font Format (version 1, .woff, supported by now by even pretty old browser versions, and version 2 .woff2 by all current versions) contain the TrueType/OpenType font as-is in compressed format, plus some XML information about it.  That means if the font is hinted, hinting is available to the browser rendeder.  (Most browsers do apply cross-origin CSS policy, meaning the web fonts have to reside in the same domain as the HTML pages used; that's why just referring to some central web repository won't work well.  Also, the set of glyphs included in the web font can be trimmed down, so you generally want to make sure you have the full font, and not someones idea of what is the useful set of glyphs from the full font typeface.)

Most fonts have been designed for printing (high-resolution devices), and only some –– Noto, DejaVu, FreeFont in particular! –– for displays ("low-resolution" devices, in this context) and with wide Unicode coverage.

(Some older fonts, like Monaco (on Mac) and Verdana (on Windows) were designed for displays, and often have very good hinting so they render well even without bitmap versions and antialiasing, but they were designed at a time when only a much smaller subset of glyphs were used: for older character encodings like MacRoman, Windows-1252 and code page 437.)

I did start a new thread in News/Suggestions/Help forum, with an example of how Dave could ensure that code snippets and teletyped text would show up the same way in all browsers regardless of what fonts the user has installed.
I do believe DejaVu Sans Mono is quite legible down to small sizes, although for the very smallest sizes (8×14 pixels for example) bitmap monospace fonts can be even better.

The same applies to all web sites, and TrueType and OpenType fonts that are licensed, or one has a license to, use on ones own web site.  So it is definitely not difficult, just a few minutes work.  The actual work is in choosing the font in the first place, such that it indeed is rendered well on all sorts of devices, and not just on the graphic artist's perfectly color-calibrated 3840×2160 retina display in a perfectly-lit office!


All that does relate to code comments, in the sense that whoever is reading the code comments, is often approaching the source codebase from a different direction than the designer/author/developer team.  Compare the situation to a graphic designer: they very often focus on what is stylish and visually pleasing, as opposed to what is functional on many different types of devices (including window sizes and resolutions). For web pages, responsive web design is the counterbalance for that.

For code, I do believe good code comments are similar counterbalance against "if it seems to work, don't care and don't touch it", related to maintainability; specifically against the "seems to work" part.  If we know the developer intent/purpose for some chunk of code, for example noted in a short useful comment, we can compare that to the actual code, and qualitatively evaluate the "seems to work" part.

For example, when fixing simple bugs, such qualitative evaluation helps pinpoint suspicious code:  I personally focus first on code that differs most from its apparent/ostensible purpose (including comments).

That also means that I believe that when one does such code review, one should be ready and willing to update, add, and remove comments, even though it provides no functional changes at all.  Just like "responsive web design" is separate from plain old "graphic design", we developers should consider code review, analysis, and comment updating a separate valued/useful task we should regularly do.

[AntiProtonBoy]

It literally takes zero effort to type in a program. You are talking the mechanics, which is typically thought-free.

This part of your argument doesn't make sense. Why would you spontaneously write code if you don't have a full picture of the problem domain you are trying to solve? 

My point is that once you understand the problem and what code needs to be written, then you'd certainly know what functions are required implementation and how you should name them. Same goes with transient stuff like variables.

So instead of writing code like this:

Code: (c++) [Select]

/*
   Make a transform matrix that maps colours from the source gamut to the
   target gamut, both specified in CIE xy coordinates.

   SR - Source red primary in CIExy coordinates
   SG - Source green primary in CIExy coordinates
   SB - Source blue primary in CIExy coordinates
   SW - Source white point in CIExy coordinates

   TR - Target red primary in CIExy coordinates
   TG - Target green primary in CIExy coordinates
   TB - Target blue primary in CIExy coordinates
   TW - Target white point in CIExy coordinates

   Returns 3 x 3 colour transformation matrix
*/
auto trColourGamut(
   const std::array< double, 2>& SR, const std::array< double, 2>& SG, const std::array< double, 2>& SB, const std::array< double, 2>& SW,
   const std::array< double, 2>& TR, const std::array< double, 2>& TG, const std::array< double, 2>& TB, const std::array< double, 2>& TW ) -> std::array< double, 9 >
   {
   // Returns matrix that transforms source RGB to CIEXYZ
   auto S = trCIEXYZ( SR, SG, SB, SW );

   // Returns matrix that transforms target RGB to CIEXYZ
   auto T = trCIEXYZ( TR, TG, TB, TW );
   
   // Make the bradford matrix
   auto B = chrmAdapt( SW, TW );

   // We concatenate the source transform matrix, bradford matrix, and the inverse of target matrix
   return S * B * inv( T );
   }

You could just adopt a self-documenting style like this:

Code: (c++) [Select]

/*
   Make a transform matrix that maps colours from the source gamut to the
   target gamut, both specified in CIE xy coordinates.
*/
auto colourGamutMappingTransform(
   const CIExy& sourceRedPrimary, const CIExy& sourceGreenPrimary, const CIExy& sourceBluePrimary, const CIExy& sourceWhitePoint,
   const CIExy& targetRedPrimary, const CIExy& targetGreenPrimary, const CIExy& targetBluePrimary, const CIExy& targetWhitePoint ) -> double3x3
   {
   auto sourceMatrix = transformCIEXYZ( sourceRedPrimary, sourceGreenPrimary, sourceBluePrimary, sourceWhitePoint );
   
   auto targetMatrix = transformCIEXYZ( targetRedPrimary, targetGreenPrimary, targetBluePrimary, targetWhitePoint );

   auto bradfordMatrix = chromaticAdaptation( sourceWhitePoint, targetWhitePoint );

   return sourceMatrix * bradfordMatrix * inverse( targetMatrix );
   }

In the second example, you can clearly deduce what the code does and what the variables mean just by looking at it. The comment block is also reduced down to just a single brief paragraph, and doesn't need an elaborate description what the function inputs mean. Also note that I don't even need to describe what the input and return data types are, because I'm using a type system that is self documenting.

The above is a toy example, but you get the gist of it. Of course, naming length can be tweaked if you find them too verbose. But the point is, they are descriptive and alleviates the extra burden of writing comments that essentially duplicates code in English vernacular.

The only place where I'd expect variables to be thoroughly documented is at public facing API boundaries that abstracts entire submodules. These are expected to appear as part of a reference manual, which may be generated via doxygen, or some equivalent scraping tool. As for private implementation details, one shouldn't need to comment code with the same granularity. Opt for self documenting programming practices instead.

Essentially, what i wrote above is the point I'm trying to make all this time. But some people here apparently view discussions about best industry practices (literally enforced by big dev houses everywhere) as being like a zealot.

And I bet none of you variable names would tell me why it is there and how it should be used.

Actually they would, because there is an economic incentive for me to use descriptive variable names. I've written massive linear algebra libraries. I've built a whole bunch of GPU render pipeline logic for computer graphics. Image processing tools. You name it. Some of these projects have gotten so large, that the only way forward is investing a little bit more effort in good naming strategies and breaking up problems into self-documenting abstractions. Otherwise, maintaining such projects would be humanly impossible, or very expensive in terms of time and money. The less time I need to spend figuring out what the code does, the sooner i can ship a product. Deciphering cryptic abbreviations and being at the mercy of good comments that describe said cryptic code is a waste of everyone's time. Because any competent developer will tell you such comments are a unicorns that do not exist in practice.

They are history and can say things that the words comprising them don't: just being wrong says a lot about the code. Of course, if one sets out thinking they are pointless then the subtle usefulness will never be noticed. Happens in all fields, that.

If you want history, you use version control systems. These are excellent at showing diffs, along with commit details, etc. An out of date comment has no business being in the file, if it no longer has any relevance to the code in its present state.

[PlainName]

Why would you spontaneously write code if you don't know the problem domain you are trying to solve?

Time constraints, perhaps. Having an outline of what you will do and filling in the details as you get to them. Any number of reasons, no doubt all of which means you're a shit programmer but nevertheless reflect real life.

So instead of writing code like this:

Frankly, the first one was good: easy to take in at a glance. Names dead easy to see and find, easy to see what is being referred to, etc. The second... well, you have to actually read it, and you can't quickly spot what you're looking for. Without the line spacing it would be wall of text stuff.

[coppice]

Why would you spontaneously write code if you don't know the problem domain you are trying to solve?

Time constraints, perhaps. Having an outline of what you will do and filling in the details as you get to them. Any number of reasons, no doubt all of which means you're a shit programmer but nevertheless reflect real life.

Its very common for people to rush into writing code with only a vague idea of what they need it to do. This might be due to external pressures, or stupidity, which are bad reasons. There are, however, good reasons. Trying to see what some of the key low level operations might look like early on can help sort out where performance bottlenecks might cause problems down the line, and meaningfully guide the detailed design.

[PlainName]

Its very common for people to rush into writing code with only a vague idea of what they need it to do.

That is the reality, and saying they 'just' need to do it properly, however you define that, isn't going to change things much. Persuading them to add some info in comments is surely better than nothing.

[coppice]

Its very common for people to rush into writing code with only a vague idea of what they need it to do.

That is the reality, and saying they 'just' need to do it properly, however you define that, isn't going to change things much. Persuading them to add some info in comments is surely better than nothing.

We have a good 60 years evidence that it isn't better than nothing. You can change the software tools. You can't change people. I wonder if AI tools may start to match comments with code in a semi-rigorous way, That could revolutionise the value of comments, forcing them to be kept current and accurate, or the code won't build.

[PlainName]

Its very common for people to rush into writing code with only a vague idea of what they need it to do.

That is the reality, and saying they 'just' need to do it properly, however you define that, isn't going to change things much. Persuading them to add some info in comments is surely better than nothing.

We have a good 60 years evidence that it isn't better than nothing.

You might have. I'm intrigued how you get that evidence, though - was it just by asking people, seeing how flummoxed it made them when reviewing code, what?

In contrast, I have 40 years of actual experience that is is better than nothing. So there 

[coppice]

In contrast, I have 40 years of actual experience that is is better than nothing. So there 

You're just a kid. When you have more experience maybe you'll see things differently.

[vk4ffab]

Why does no-one write comments any more? Not even just something to say what the function is meant to do, never mind the intricacies of how it goes about that. Some cryptic 12-character name may mean something to the programmer but it's bugger-all use when coming afresh to get a birds-eye view of things.

And variables! Really, do babies die or something if you let on WTF a variable is about?

Here's the thing. The code I write is for me. If I feel nice and share my code, I expect the end user to be smart enough to read the code and understand how it works, if they are not smart enough to do that then its tough tits. If I was contributing code to someone else's project, I would comment as per the project standard.

Mostly though I have stopped sharing code I write because of the number of people that write to tell me I am a dumb dumb head because they were to stupid to read the code to work out what library they were missing and I am just to old and cranky to hold people's hands to do things beyond their skills and abilities.

[PlainName]

Way to go, Team Player 

[JPortici]

Why does no-one write comments any more? Not even just something to say what the function is meant to do, never mind the intricacies of how it goes about that. Some cryptic 12-character name may mean something to the programmer but it's bugger-all use when coming afresh to get a birds-eye view of things.

And variables! Really, do babies die or something if you let on WTF a variable is about?

Here's the thing. The code I write is for me. If I feel nice and share my code, I expect the end user to be smart enough to read the code and understand how it works, if they are not smart enough to do that then its tough tits. If I was contributing code to someone else's project, I would comment as per the project standard.

Mostly though I have stopped sharing code I write because of the number of people that write to tell me I am a dumb dumb head because they were to stupid to read the code to work out what library they were missing and I am just to old and cranky to hold people's hands to do things beyond their skills and abilities.

fair
however the older i get the lazier i am and i'm too lazy already to work out what two-year-ago me did and why he did it. curse that lazy bastard for not commenting. so over time i reached a sweet spot for comments, variable and function names, also stripping away all possible "clever" things i did in the past unless they were really, really, really justified. The truth is that i'm always part of a team even when i'm the sole developer, and the other team member is my past self (or my future self, depending on how you look at it) which counts toward "another person that has to read and understand the code"

[vk4ffab]

Why does no-one write comments any more? Not even just something to say what the function is meant to do, never mind the intricacies of how it goes about that. Some cryptic 12-character name may mean something to the programmer but it's bugger-all use when coming afresh to get a birds-eye view of things.

And variables! Really, do babies die or something if you let on WTF a variable is about?

Here's the thing. The code I write is for me. If I feel nice and share my code, I expect the end user to be smart enough to read the code and understand how it works, if they are not smart enough to do that then its tough tits. If I was contributing code to someone else's project, I would comment as per the project standard.

Mostly though I have stopped sharing code I write because of the number of people that write to tell me I am a dumb dumb head because they were to stupid to read the code to work out what library they were missing and I am just to old and cranky to hold people's hands to do things beyond their skills and abilities.

fair
however the older i get the lazier i am and i'm too lazy already to work out what two-year-ago me did and why he did it. curse that lazy bastard for not commenting. so over time i reached a sweet spot for comments, variable and function names, also stripping away all possible "clever" things i did in the past unless they were really, really, really justified. The truth is that i'm always part of a team even when i'm the sole developer, and the other team member is my past self (or my future self, depending on how you look at it) which counts toward "another person that has to read and understand the code"

I kind of do the same things, but it does depend on the level of complexity within the code. Much of what I write these days is for micro's and 1000 lines of code would be a rather big program where much of it is rather boring and run of the mill. None of this is the Linux Kernel so unless I do something cryptically because i resource limitations, I dont bother explaining much at all where it should be rather obvious what is happening. If I cant read the code and work out what is going on, i dont deserve to be working on it HAHAHA

However, when i contribute code to other projects, I am pretty liberal with comments on things that would be non obvious to anyone familiar with that code. Something like MyNumber = Ch->Level; I am not going to explain what Ch or Level are, because they are obvious to anyone who works with that code, but i would explain what I am doing with MyNumber if what followed was non trivial to the reader, with a couple of lines of comment above the function to explain its purpose and why I added it.

Hence my reply to the OP. How much hand holding does one require? Take a look at the comments in the Linux kernel. There is an expectation there that you actually understand something of the code before you work on it. Its not like the OP had any specific example of what he was complaining about, just a generic complaint about naming conventions and a lack of commenting. Perhaps, its more that he just lacks the skills and knowledge to be working on a piece of code in the beginning rather than there being a lack of commenting or naming convention.

I have worked smallish projects with half a million lines of code and yeah I have spent a few days reading the documentation and working through the code to understand it before I started to do anything and I am a hobby coder not a industry professional. Sometimes you have to put in a little more effort than plugging the blinky into the arduino and calling oneself a coder.

[PlainName]

Hence my reply to the OP. How much hand holding does one require?

I explained in the thread. One thing I do is a high level read of what the files are for, what the functions in it do, why they exist, so I know if this is the file I am looking for, or just getting a picture of wtf this project is. "Functions to implement double-ended linked lists" tells me a lot in 1.5 secs that spending 5 mins scanning the code or trying to make sense of stupid filenames probably wouldn't.

Comments are most use when not writing or changing code.

[tggzzz]

Hence my reply to the OP. How much hand holding does one require?

I explained in the thread. One thing I do is a high level read of what the files are for, what the functions in it do, why they exist, so I know if this is the file I am looking for, or just getting a picture of wtf this project is. "Functions to implement double-ended linked lists" tells me a lot in 1.5 secs that spending 5 mins scanning the code or trying to make sense of stupid filenames probably wouldn't.

Comments are most use when not writing or changing code.

I don't see why some people find that hard to comprehend!

I'll emphasise your point, again, by pointing out that a comment indicates what you don't need to look at.

[SiliconWizard]

Yes, that point was already made early in the thread.
To illustrate the point in maybe a slightly different light, think of writing code as you'd write text in a natural language, which Knuth and Wirth (among others) have been famous advocates of.
That basically means that comments should be used, IMO, as titles and footnotes when writing books and articles.

The "title" class of comments indicate what the following piece of code deals with. You have different levels of titles, like you have different levels of titles when writing text (entire text, chapters, sections, subsections, etc). Remove those titles entirely and any article or book will become nearly unreadable - and at the very least, very unpleasant to read. But organize your sections with a bit of common sense. Because conversely, A book with 1-sentence long sections or chapters would look annoying and ridiculous.

The 'footnote" class of comments detail a particular point in code that requires being developed a bit (so, more like the "how" category) when it's not obvious and when writing the code to make it more obvious (so not requiring any comment) would either be impossible, or unnecessarily heavy (and thus possibly more bug-prone). Just like you use footnotes when writing text, to detail a point that would be hard to detail in the main text itself, or make it unpleasant to read, or to follow the general line of thought. And so, just like with footnotes with natural language, use them sparingly. Again, imagine a book with a footnote at every other word, that would be a major pain to read and would show a clear problem in organizing one's thoughts and expressing them.

I've noted that there was some exxageration too in the discussion, and quite a bit of all-or-nothing statements, but that's not uncommon in any kind of discussion. For instance, about self-explanatory identifiers. Which are almost completely orthogonal to the question of commenting as described above anyway. For sure, use identifiers that are at least a bit descriptive, that helps readability a lot. But you don't need to make them 100-character long, that is exxageration and would be ridiculous.

[vk4ffab]

Hence my reply to the OP. How much hand holding does one require?

I explained in the thread. One thing I do is a high level read of what the files are for, what the functions in it do, why they exist, so I know if this is the file I am looking for, or just getting a picture of wtf this project is. "Functions to implement double-ended linked lists" tells me a lot in 1.5 secs that spending 5 mins scanning the code or trying to make sense of stupid filenames probably wouldn't.

Comments are most use when not writing or changing code.

While these are things you do, when it comes to code downloaded from the internet, its a lottery. Much of what gets written is about solving a problem that the author has, it was never meant for an end user or corporate client. How they go about it is their business and if they write a pile of crap that is impossible to understand the solution is simple, write your own code from scratch. And my comments have all been about addressing the 3 main points you make in your OP.

Why does no-one write comments any more? Not even just something to say what the function is meant to do, And variables! Really, do babies die or something if you let on WTF a variable is about?

As I stated in my first comment, the audience for my code is me, no one else even if I share it because it might have utility to others. But its all on them to understand it if they want to do more with it than just compile and use. So again, if i am writing code to solve a problem I have, what do I owe anyone to provide any level of documentation? Or name all my variables and functions something other than A, B, C etc. If my code is crap and unreadable, just do not use it. So again, how much hand holding do I or other authors owe anyone? 

Cant comment for others, by my  naming conventions are all about me being able to understand things later MyFuntionDoesThis and MyVariableHoldsThat I tend to be quite verbose and only add comments when and where what I have written is non obvious or uses some cryptic way of doing things in C.

[tggzzz]

Yes, that point was already made early in the thread.
To illustrate the point in maybe a slightly different light, think of writing code as you'd write text in a natural language, which Knuth and Wirth (among others) have been famous advocates of.
That basically means that comments should be used, IMO, as titles and footnotes when writing books and articles.

The "title" class of comments indicate what the following piece of code deals with. You have different levels of titles, like you have different levels of titles when writing text (entire text, chapters, sections, subsections, etc). Remove those titles entirely and any article or book will become nearly unreadable - and at the very least, very unpleasant to read. But organize your sections with a bit of common sense. Because conversely, A book with 1-sentence long sections or chapters would look annoying and ridiculous.

The 'footnote" class of comments detail a particular point in code that requires being developed a bit (so, more like the "how" category) when it's not obvious and when writing the code to make it more obvious (so not requiring any comment) would either be impossible, or unnecessarily heavy (and thus possibly more bug-prone). Just like you use footnotes when writing text, to detail a point that would be hard to detail in the main text itself, or make it unpleasant to read, or to follow the general line of thought. And so, just like with footnotes with natural language, use them sparingly. Again, imagine a book with a footnote at every other word, that would be a major pain to read and would show a clear problem in organizing one's thoughts and expressing them.

I've noted that there was some exxageration too in the discussion, and quite a bit of all-or-nothing statements, but that's not uncommon in any kind of discussion. For instance, about self-explanatory identifiers. Which are almost completely orthogonal to the question of commenting as described above anyway. For sure, use identifiers that are at least a bit descriptive, that helps readability a lot. But you don't need to make them 100-character long, that is exxageration and would be ridiculous.

Those are useful analogies, insofar as any analogy is useful.

Too many people think (and I use that word loosely) along these lines:

• I've had to deal with crap code
• that code has had crap comments and maliciously complied with coding standards
• such crap comments are worse than useless
• therefore comments are crap
• therefore comments should be removed

The fallacy is obvious, when you think about it.

In my experience, code with good comments doesn't need to be changed when it is used. A good comment indicates thought, and that is reflected in the code quality.

[PlainName]

That basically means that comments should be used, IMO, as titles and footnotes when writing books and articles.

That's a good take on it, yes 

[PlainName]

While these are things you do, when it comes to code downloaded from the internet, its a lottery.

Oh, you noticed what this thread is about after all!

As I stated in my first comment, the audience for my code is me ...

No problem with whatever you want to do for youself. Some people like a spotless and tidy worktop where others are unable to see the mess they leave behind and are forever searching for tools that are 'somewhere'. But whatever floats your boat is between you and your keel.

... no one else even if I share it because it might have utility to others. But its all on them to understand it if they want to do more with it than just compile and use. So again, if i am writing code to solve a problem I have, what do I owe anyone to provide any level of documentation? Or name all my variables and functions something other than A, B, C etc. If my code is crap and unreadable, just do not use it.

Well, some people like to be helpful and others don't give a toss. "I would like to make this a painless experience if I can" vs "fuck 'em, it's free", perhaps. Again, whatever floats your boat, but now the material of your keel is common knowledge.

So again, how much hand holding do I or other authors owe anyone?

'Owe'? Nothing, nada, zero, zilch. But an enlightening question.

[vk4ffab]

Well, some people like to be helpful and others don't give a toss.

'Owe'? Nothing, nada, zero, zilch. But an enlightening question.

And there are a lot of people on the internet who think they are owed the corporate client experience and 24/7 support for stuff posted on github. Demand it even. And while you try and make this about me being a mean old man who is not helpful, not a team player and does not give a toss, my position is a rather simple one, if you wanna use my stuff, you are going to have to put some effort in here and at least understand the fundamentals of what is going on if you want to change it in anyway. That is pretty much the condition of entry into all open source.

[PlainName]

And while you try and make this about me being a mean old man who is not helpful, not a team player and does not give a toss

Yes, that's unwarranted and I apologise.

[vk4ffab]

And while you try and make this about me being a mean old man who is not helpful, not a team player and does not give a toss

Yes, that's unwarranted and I apologise.

All good.

[helius]

For most part programming is nothing more than translating from an imprecise concept expressed in human terms to a precise language understood by a machine.

"Our design ... reflects two major concerns. First, we want to establish the idea that a computer language is not just a way of getting a computer to perform operations but rather that it is a novel formal medium for expressing ideas about methodology. Thus, programs must be written for people to read, and only incidentally for machines to execute." -- Abelson and Sussman, Structure and Interpretation of Computer Programs, from the Preface to the First Edition

The logical extension of this idea was brought out by Donald Knuth in the 1980s. If programs are primarily texts written for other humans, and only secondarily for computers to run, the relationship of code and comments should be inverted: the dominant or overarching element should be expository writing (the "comments"), with executable code snippets included in it passim.

Knuth published a book on this idea, describing a software package (CWEB) that compiles these Literate Programs into files a compiler can use. https://www-cs-faculty.stanford.edu/~knuth/lp.html

[PlainName]

That does make sense. After all, if it were primarily about the computer we'd be writing assembler, and that only because we just wouldn't be able to remember the hex codes for instructions.