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!