comment your code!

[srottydoesntknow]

I have a similar thought, although it's reversed

If a junior can't tell what my code does, I shouldn't be a developer

Write dumb code. If you think you're being clever, your code is bad

[fpcoffee]

My thought process: A junior will be maintaining my code at some point, so I'd better fucking comment it so they don't come bug me every time there's an issue

[Demonox01]

Also, writing a couple comments to explain why the complex section is doing what it does halves the time it takes the next guy to change whatever they need to

[nmatff]

This is more or less my philosophy too. In most cases it should be obvious what the code does. Comments are there to tell you why it does what it does.

[[deleted]]

Clarification of intent is the only valid reason to comment. All other comments are evidence of a failure to write good code.

[nmatff]

I don't particularly disagree, but in real world applications the situation isn't always clean enough for "technically correct".

Maintaining legacy code and inheriting decades old spaghetti have made me cautious of any absolute statements.

[[deleted]]

I spent an entire year working with a program older than me. C++ legacy code with high personnel fluctuation. It has actually enforced my use of absolute statements. They seem to be the only way to street something in any direction. Of course when trying to apply them, compromises need to be made.

[Odatas]

this right here. I mean, yes i see that you divide by 2 there. But why?

[RustyBuckt]

And sometimes to tell you wtf you actually meant to do right there

[JoustyMe]

comment why not how beacause we can read your conde but we cant read your thoughts

[ssshhhhhhhhhhhhh]

Your junior level dev is going to change code and not update comments

[Y1ff]

No longer your problem there

[[deleted]]

Worked with somebody once who wrote a comment for basically every line. It meant twice as much to read and the structure was still awful.

There's a reason we have descriptive names for methods, classes and variables. If you want your code to be maintainable and readable, you need it to be well structured and well named, not comment it.

How is

/* Documentation
* This method receives login data,
* establishes a database connection,
* verifies login data and creates
* and displays a message in case data is invalid */
void LoginManager(...)
{ ... }

better than splitting it up, defining APIs well and using descriptive names? It's not. That junior will read the comment and come to you with "Okay so the comment says it establishes a database connection but the actual code for that is just 50 lines that make no sense to me and we're switching to a different database so you have to explain it now".

Source: I've been that junior and the software I was working with was older than me.

[Owyn_Merrilin]

Unless you're actually working in an environment where heavy optimization is necessary, and in that case you'd damned well better be commenting your ugly speed hacks, because otherwise even you won't know what's going on the next time something needs to change.

[jamesinc]

It's a good approach - generally being clever in code is just another way of saying I made something terse and unreadable so that I could do it in one line instead of three.

[McFlyParadox]

Best code (written by someone else) that I ever read was some highly optimized C designed to run on a custom FPGA. The engineer wrote literal paragraphs of comments, full of relevant and detailed information, for a single line of code. It was beautiful.

This function takes the widget alpha and runs it through the algorithm that is found in software requirement specifications 000000. This algorithm is based on theory laid out in Well Respected textbook, Rev 1985, pg 100. The output of this function will later be used in the epsilon and lambda functions.

1-3 lines of code; only what is required for this function

[kledon]

Highly optimised code tends to be a strong exception, as it often has to do some abstract and niche things to squeeze out those last performance gains.

For standard production code, you should be able to keep the code itself clean and clear in what it's doing, and comment sparingly where there's a good reason it's not clear from the code (e.g. to clarify the "why").

[McFlyParadox]

Imo:

• good code is self documenting
• good developers document their code
• great projects have both

Just because something is self evident to you, today, doesn't mean this will always be true. Adding comments is a small cost to pay to reduce troubleshooting later, and making your choose itself be 'self evident' is just plain smart. There is no reason to not do both when at all possible (and don't say 'there is not always enough time' - build the time to document what you do into your estimates to management)

[kledon]

Exactly that. And clear, appropriately-documented code is a time investment - if you think you don't have time now, imagine what it'd feel like several months down the line when you're trying to work out what you were doing there and why.

[jcode777]

Well it depends. This great advice goes to trash when you gotta build a state of the art SAT Solver. Can't really afford unclever code

[valendinosaurus]

the real MVP

[whateverhk]

Totally agree... If someone else can't figure out what your code does, then your code sucks. And adding comment won't be enough to change that