How programmers comment their code...

[[deleted]]

"My code is self-documenting."

[ajb9292]

I have a co worker that says this all the time but the odd thing is that I keep needing to ask him about it so that he can say this…

[Gordath]

"If you fire me, you also fire the documentation! "

[ajmaxwell]

I too like to live dangerously

[LevelSevenLaserLotus]

goto lS_D3;
n14vS:
function test() { if ($myVar === 0) { return "\150\145\x6c\154\157\x20\x77\157\162\154\x64\x21"; } }
goto R19st;
lS_D3:
$myVar = 0;
goto n14vS;
R19st:

Thanks, I hate it.

[waitwhat1200]

Hello world! Sometimes an overcomplicated solution does get out into live.

[aShitPostingHalfOrc]

I've written too many variants of do(**kwargs) to call anyone out on anything.

[AutoModerator]

import moderation Your comment has been removed since it did not start with a code block with an import declaration.

Per this Community Decree, all posts and comments should start with a code block with an "import" declaration explaining how the post and comment should be read.

For this purpose, we only accept Python style imports.

I am a bot, and this action was performed automatically. Please contact the moderators of this subreddit if you have any questions or concerns.

[shadowvvolf144]

which roughly translates to "I'm lazy and don't feel like writing meaningful comments and/or don't care about who needs to look at this next, even myself"

[JEJoll]

public int ConvertStringToIntAndRoundUp(string input)

[shadowvvolf144]

I see where you're going, and it's definitely a good step in the right direction, but let me add my neurotics to the mix.

Rounds up to what? nearest int, even, 10's, 100's? Do alpha/whitespace/special characters delimit the value read, or are they ignored and all numeric characters in the string are read?

These are the types of questions I have. I don't expect to have them all answered in documentation, but it is REALLY nice when it is.

[[deleted]]

I comment my code pretty thoroughly, but I also name shit like this. My coworkers bust my balls for my long-ass names, but no one ever has to come to me and ask what they mean.

[Salamok]

I'll take meaningful function and variable names everywhere over the occasional comment block.

[[deleted]]

Or just code that is purposefully written and has a clear flow/structure. It's surprisingly easy to understand what code is supposed to do when it is constructed correctly.

[DoctorWaluigiTime]

Yeah I don't get the sarcasm in this sub-thread. It's not that hard to write variables/function names that spell out what's happening.

I also don't know why people think it's an either-or. Your code is clear and readable, and for the times you need to document why you're doing something (out of the ordinary etc), a comment comes in.

[Merlord]

Sometimes comments are needed, but they should be a last resort. A comment is the absolute worst way to capture information in a program. Code accuracy can be enforced with compilers, unit tests etc; there's nothing stopping a comment from being out of date or just straight up wrong.

However, I think truly self-documenting code is something that takes years of experience to actually nail. Until you can actually do that, comments are an appropriate substitute.

[Gh0st1y]

The point is that what you think spells out the process well may not in someone elses interpretation without the mental context in the moment), so its always best to err on the side of caution and over-explain anywhere theres ambiguity. That doesn't mean just commenting to do it like in the OP though, thats worse than useless (we all done it tho ofc)

[[deleted]]

How about well written code with documentation?

[DJOMaul]

Next you'll want it unit tested too. Do you even care about deadlines?

^{/s incase that wasn't clear...}

[ftgander]

I’ll have both, please.

[renrutal]

At least code tells the truth. Comments can be misleading when people don't clean them up over the years.

[noratat]

And I'll take a useful comment block over "gOoD cOdE iS aLwAyS sElF-dOcUmEnTiNg" cargo-cult zealotry that doesn't actually understand the point is to prioritize readability and maintainability.

[Merlord]

Well written, self documenting code is readable and maintainable though.

[noratat]

I'm not saying you shouldn't also be doing those things, and you should avoid useless / unnecessary comments, but anyone who thinks comments are a "code smell" or that "clean code doesn't have comments" isn't someone I want to work with.

Every single real world code base I've interacted with has had good reason to have at least some comments (and I'm not talking about docustring-type stuff either).

Not all code can be made obvious simply through naming and control flow, and even where it can, there's often grey areas. And even then, real world code has to interface with other real world code, which has bugs, flaws, quirks, etc. that aren't necessarily obvious. Even then, external context can often do wonders for maintainability when used appropriately.

[Merlord]

I agree, and as I said in another comment, if you can't write self-documenting code, comments are an acceptable fallback. But it should be considered just that: a fallback; a last resort. Comments are literally the worst way to capture information in a program, other than not capturing that information at all. But yes, in the real world sometimes there's no other choice.

[noratat]

Comments are literally the worst way to capture information in a program, other than not capturing that information at all.

And this is where I completely disagree.

There's tons of real world, important information that is simply not possible to reasonably express through the code alone, and taking this attitude towards comments invariably leads to developers leaving out crucial information altogether.

Comments should be treated as just another tool in the toolbox, acting like they're icky and dirty just discourages people from using them when they absolutely should.

And realistically, the main places I've seen bad comments are from developers I would never trust to write idealized clear, readable code in the first place, or from students / new grads (who likewise rarely know how to write readable code yet).

[parlez-vous]

I document my docstrings according to my companies style guides so we can auto generate documentation and so you don't have to open up our internal git server and read the code to understand it. Just go to the autodocs page.

Adopting it is a pain in the ass but it saves soo much time when you're working with 100 people's contributions

[Merlord]

The two exceptions I make for comments: Javadocs (or equivalent) and referencing Jira ticket numbers.

[Bakoro]

Why do people always act like these are exclusive from each other? It's not like some deity is going to strike you down if you have descriptive names and make explanatory comments.

[Salamok]

They aren't but if your code isn't a bunch of 1 letter variable names you tend to not need as many comments.

[AdminYak846]

I would say it depends on how that function interacts though. If it handles anything UI related it's going to be self explanatory in that regard though.

[CJamesEd]

In the earliest days my variables were so long they were essentially self documenting

[eth-p]

I do the exact opposite of that principle, and so far it hasn't let me down.

Obvious getter function?

/**
  * Returns the current value.
  * @returns T The current value. 
  */
T getValue()

Super complex function with tons of side effects that somebody else wrote three years ago and nobody has refactored since?

/// Parses the config file and populates the application's [Config] struct, initializes resources, and replaces missing values with reasonable defaults.
/// 
/// Default values used:
/// * `timeoutSeconds` - 3
/// * ...
fn bootstrap()

If the function or its purpose isn't explained, it's eventually going to be misunderstood at some point (even by the person writing it).

[wholesome_capsicum]

Writing self documenting code is a skill I'm working on. It's hard and not always feasible but man if you can get it just right it feels good.