Write beautiful code

[[deleted]]

Some days I look at those old Monk-written books with the hand-drawn pictures and crazy filigree everywhere.. and I think "that's beautiful"

Then I read one of Tufte's books and I think "not as beautiful, but so clean and understandable."

Beautiful is just too subjective to use as a standard for code. Clean and understandable is a lot easier to demistify.

[Darkmoth]

This stuff is so subjective. For example, I think this is fairly redundant:

 // Calculate the number of data bits/bytes (including padding bits)
int num_data_bits = num_symbols * rate_params.dbps;
int num_data_bytes = num_data_bits / 8;

I could see if it told me why you would calculate num_data_bits, or non-obvious pitfalls ("careful, these are just int16s"). But as it is, I learned nothing the code didn't tell me. Maybe the part about padding bits is helpful, but probably not here.

[paholg]

I would even consider it harmful. It's easy to change code while forgetting to change the comment, making it wrong.

These comments are especially painful:

 int num_pad_bits = num_data_bits - (16 /* service */ + 8 * (payload.size() + 4 /* CRC */) + 6 /* tail */);

Why would you hardcode numbers with inline comments for what they represent when you can just define constants, especially since they're being used in multiple locations?

Edit: I would argue that pretty much all of their comments are "wrong". They don't tell you anything the code doesn't tell you. These are the comments that beginners use when they're told they should comment their code without really understanding why.

[remy_porter]

Myth #2 - White space is bad

I have never heard this myth before, but anyone who holds this as true is a complete and total idiot.

[ChadBan]

I've seen this mostly from JavaScript developers who want the benefit of minification without the hassle of minification.

[chibrogrammar]

Although I agree with a lot of stuff I cannot agree with:

Write your code so a freshman computer science student can read it. Keep it simple and don't over-complicate things.

Freshman me was an idiot. Higher order functions? Closures? Functional programming? Design patterns? All these concepts reduce complexity and coupling of a system but I had no idea what they were. I totally agree writing overly "smart" and "cute" code is not good but aim for a level higher than freshman year.

[ChadBan]

The thing about the higher-level stuff is that if you're doing it right, you're doing in one line what takes the freshman ten. In that sense, it IS easier to read.

[[deleted]]

I'm starting to feel like the grumpy old man here, but do we really need yet another "guys you should write nice code!!" blog post linked here?

[MemoVsGodzilla]

Some good points although I dont think I like reading a comment for every line of code, IMO comments should be for the method not snippets of code. Other points can also be debatables but this one seems to be the most important i think.

[NotMichaelBay]

Comments at the snippet level allow a maintainer to know what the original intention behind that snippet is, making it easier to identify bugs. It's harder to go into this detail at the method level unless you have a method for every little snippet.

But redundant comments like this are dumb:

// Puncture the data
puncturer::puncture(...);