undefined | Better HN

0 pointsathenot8y ago0 comments

Besides, code speaks to the compiler/runtime; comments speak to the human.

- The machine need to know HOW something should happen. That's code.

- The human needs to understand WHY that thing should happen that way.

These are two different objectives, and good quality code weaves the two in the appropriate measure.

Having said that, I don't believe all code should be reduced to the subset that a junior dev can understand. Keep it simple when possible, yes. But don't limit yourself, otherwise it's just a shift to verbosity, eating into the finite attention span within the brain. Rather, if the intent is properly documented, then the junior devs can still work on the parts of the code they understand, and reach out to a senior dev when they need to touch the part they don't understand, because even if they don't quite grasp the "how", they can follow the "why" in the code.

0 comments

darkerside8y ago

Wrong. Machine code is for the computer. Human readable high-level languages were designed specifically for people.

wolco8y ago

Different newspapers write to different education levels. In your local paper you may find writing that a grade 8 student could understand. In your industry specific journal the writing may be at a grade 12 level.

Not all code should or can be human readable by all.

darkerside8y ago

Right, and some people will work in C, while others will work in Python. That doesn't quite line up with a "grade level", but I agree that different writing styles (or languages) suit different purposes best.

But I assure you, our computers would "think" that we are all idiots for using just about any high level language feature. We write things in loops (computer unrolls it), we give variables readable names so we can think about them (computer assigns it a memory address instead), and we build meaningful abstractions (computer sighs and turns it into meaningless 1s and 0s). So literally all high level languages are written for us feeble-minded HUMANS! Not for computers.

ithkuil8y ago

yeah. I've seen a lot of comments like:

    // Sleep for 10 minutes
    sleep(15*60)

Unfortunately, the compiler cannot check your comments. Don't put facts that are better looked up in the actual code and that they only risk getting out of sync with the code.

athenotOP8y ago

That's a useless comment. A better one would be:

    // Prevent the two tasks from running right after each other,
    // to reduce load when this is run frequently
    sleep(15*60)

Even the most junior dev can infer that a multiplication by 60 for a sleep function probably means the unit is seconds and we want 15 minutes. No need to spell that out. But why sleep for 15 minutes and not just carry on to the next task? THAT is what the comment is for.

Clubber8y ago

Exactly. Comments are for intent, not what the code does. If I want to know what the code does, I can just read the code.

crdoconnor8y ago

I've found a better approach to comments is not to put them in at all.

Then, you raise a PR, have a code review, and whatever the other developer is confused about that you had to explain to them - that's where you needed a comment and what you explained to them is what the comment should be.

Developers who have their "head in the code" will almost always (unless they are very smart and very empathetic) fail to realize what is hard for other developers to understand because they will fail to accurately model to context which the other developer has.

BoorishBears8y ago

And to keep with the theme of self-documenting, the self-documenting version of that would be:

    NAP_LENGTH_MINUTES = 15;
    ...
    sleep(NAP_LENGTH_MINUTES*60);

Clubber8y ago

Still not good enough. Why is this nap function in there? If I want to make it faster and didn't know, I would just remove all references to it. What did I break? Can't tell by that variable name.

1 more reply

diggan8y ago

> Besides, code speaks to the compiler/runtime; comments speak to the human. > - The machine need to know HOW something should happen. That's code. > - The human needs to understand WHY that thing should happen that way.

While valuable, some people argue that they should be the same (granted, I mostly deal with high-abstraction language). For example most (all?) lisps have homoiconicity which means the computer and you see the code the same.

pjc508y ago

Homoiconicity is irrelevant - comment text has no meaning to the computer but can do for the human. Computers have a hard time with "why".

j / k navigate · click thread line to collapse

0 comments

darkerside8y ago

Wrong. Machine code is for the computer. Human readable high-level languages were designed specifically for people.

wolco8y ago

Not all code should or can be human readable by all.

darkerside8y ago

ithkuil8y ago

yeah. I've seen a lot of comments like:

    // Sleep for 10 minutes
    sleep(15*60)

Unfortunately, the compiler cannot check your comments. Don't put facts that are better looked up in the actual code and that they only risk getting out of sync with the code.

athenotOP8y ago

That's a useless comment. A better one would be:

    // Prevent the two tasks from running right after each other,
    // to reduce load when this is run frequently
    sleep(15*60)

Clubber8y ago

Exactly. Comments are for intent, not what the code does. If I want to know what the code does, I can just read the code.

crdoconnor8y ago

I've found a better approach to comments is not to put them in at all.

BoorishBears8y ago

And to keep with the theme of self-documenting, the self-documenting version of that would be:

    NAP_LENGTH_MINUTES = 15;
    ...
    sleep(NAP_LENGTH_MINUTES*60);

Clubber8y ago

Still not good enough. Why is this nap function in there? If I want to make it faster and didn't know, I would just remove all references to it. What did I break? Can't tell by that variable name.

1 more reply

diggan8y ago

pjc508y ago

Homoiconicity is irrelevant - comment text has no meaning to the computer but can do for the human. Computers have a hard time with "why".

j / k navigate · click thread line to collapse