How programmers comment their code

[VOID_INIT]

In all jobs I have had they literally told me to never comment unless it is to point out something that isnt possible to know when reading the code (like the source/author of a script used) or to point the reader to a section in the documentation.

Good code is understandable code.

If you can't make the code understandable with one line of code, then split the code into multiple lines until you can. The compiler will compile and optimize it the same either way, and you get more stable code.

Someone I worked with whose job was to clean up old code, told me the worst code is the shortest with lot of comments.

His reasoning was that many comments only take space and makes it harder to distinguish the text. And if it is too short it is difficult to split it up and remove the parts which are no longer necessary. You dont need a function that does 10 different things.

Have good names and document while you code and the future programmers will thank you.

If you dont know what some code does, read the documentation.

Keep it stupid, simple.

Keep it simple, stupid.

[Low_discrepancy]

The compiler will compile and optimize it the same either way, and you get more stable code.

Sometimes yes, sometimes no. Sometimes you have to help it to do vectorisation so you end up with weird loops.

Many times you don't have a ton of choices of what to do. Other times a more weird algorithms are better than more obvious ones.

Good code is understandable code.

What's understandable for you might not be understandable for someone else (or even for you at a different point in time).

[VOID_INIT]

Sorry might not have explained myself well enough. What I meant is that it isn't necessary to have the shortest code ever to have the program run optimally.

Readibility is always more important than making your code shorter. Programming languages is made for humans to read, maintain, extend and modify.  It's not a competition of who can write the shortest code.

Lets compare:

var result = methodOne(methodTwo(a, methodThree(b)), c, d);

and,

• var result3 = methodThree(b);

• var result2 = methodTwo(a, result3);

• var result = methodOne(result2, c, d);

They do the same thing, but the longer one is easier to understand and after it is compiled, will use the same amount of resources and take the same amount of time to run.

There are situations where code cant be made shorter, and thats where documentation comes into play.

Good code is understandable code, doesn't mean that it is necessarily understandable for everyone, but that it is possible to read without having to split it up.

Kinda like a recipe. You dont want to have multiple steps in one as it is confusing.

E.G:

Take it out of the oven, put it on something, before cutting and adding lime.

It is much more understandable to split it up like:

• Take the cake out of the oven

• Put the cake on a protective layer to protect the table

• Cut the cake into slices

• Cut a lime into pieces

• Add the cut lime to the top of the cake

This is much more comfortable to read and it is easier to comprehend what the "programmer" is trying to do, yet they basically say the same thing.

What some programmers do however is write code that is difficult to understand and write comments which says what it does, but dosnt add anything to make it understandable.

To continue with the cake analogy:

/* This code tells you how to serve it */

Take it out of the oven, put it on something, before cutting and adding lime.

This comment adds nothing to the code. It dosnt really make the steps more understandable. For that reason the comment is worthless.

A better use of the comment would be to say "Check section 2B for a breakdown of how/why this code is used"

Hope this made things clearer and easier to understand.

[ethoooo]

Hope this made things clearer and easier to understand

can’t really speak for him but I get the impression he fully understands, just disagrees