1166
Comenting code (lemmy.ml)
top 50 comments
sorted by: hot top controversial new old
[-] essteeyou@lemmy.world 124 points 6 months ago* (last edited 6 months ago)
/**
 * Gets the user
 **/
fun getUser() {
    return this.user;
}
[-] some_guy@lemmy.sdf.org 33 points 6 months ago

I'm sorry, I don't think I understand what's happening here…

[-] essteeyou@lemmy.world 27 points 6 months ago

Let me find the sequence diagram...

[-] jaybone@lemmy.world 12 points 6 months ago

You need the requirements doc from marketing. Then it will all totally make sense for sure. No cap.

load more comments (1 replies)
[-] lord_ryvan@ttrpg.network 8 points 6 months ago* (last edited 6 months ago)

Okay now I get the joke.
I hate these kind of people.

By the way, your ``` both need to be on their own, separate line

load more comments (5 replies)
[-] JasonDJ@lemmy.zip 82 points 6 months ago

My comments are just the code that didn't work but I don't want to delete yet because I might make it work except I never will be cause I already rewrote it so it does.

[-] Sparky 52 points 6 months ago* (last edited 6 months ago)

Hey thanks for reminding me I made a clock squared in blender about 2 years ago

yes there is an error in the image, and no I'm not telling you where it is

[-] oo1@lemmings.world 44 points 6 months ago

at 6 it says 12:30

[-] xmunk@sh.itjust.works 11 points 6 months ago

1 o'clock and 10 o'clock are the the wrong angles.

[-] lord_ryvan@ttrpg.network 5 points 6 months ago

You mean they're slightly off? Like 7:00?

[-] xmunk@sh.itjust.works 4 points 6 months ago

Yup, like 7 PM.

[-] bstix@feddit.dk 6 points 6 months ago* (last edited 6 months ago)

11 is missing the hour hand in the miniatures.

[-] cmhe@lemmy.world 4 points 6 months ago

An interesting concept would be if all hand on the 12 clocks would work, but the hands of the clock in the middle are stuck at 12 position, this way the hands in the middle would point to the clock showing the correct time.

load more comments (1 replies)
load more comments (7 replies)
[-] goatmeal@midwest.social 32 points 6 months ago

I know I’m probably doing it wrong but this is how I feel whenever I write unit tests

[-] some_guy@lemmy.sdf.org 21 points 6 months ago* (last edited 6 months ago)

Checked one of mine:

# get path to the download directory

Oh, ok.

[-] darkpanda@lemmy.ca 25 points 6 months ago

The code directly below:

function getPathToUploadDirectory() {
  return config.tmp_path
}
load more comments (1 replies)
[-] jonathanvmv8f@lemm.ee 21 points 6 months ago* (last edited 6 months ago)

Asking as a newbie programmer: how do you suggest we write comments that explain the 'why' part of the code? I understand writing comments explaining the 'what' part makes them redundant, but I feel like writing it the former way isn't adding much help either. I mean, if I created code for a clock, is writing "It helps tell what time it is" better than writing "It is a clock" ?

It would really help if someone could give a code snippet that clearly demonstrates how commenting the 'correct' way is clearly better than the way we are used to.

[-] pixelscript@lemm.ee 19 points 6 months ago* (last edited 6 months ago)

I recognize three kinds of comments that have different purposes.

The first kind are doc block comments. These are the ones that appear above functions, classes, class properties, methods. They usually have a distinct syntax with tags, like:

/*
 * A one-line description of this function's job.
 *
 * Extra details that get more specific about how to use this function correctly, if needed.
 *
 * @param {Type} param1
 * @param {Type} param2
 * returns {Type}
 */
function aFunctionThatDoesAThing(param1, param2) {
    // ...
}

The primary thing this is used for is automatic documentation generators. You run a program that scans your codebase, looks for these special comments, and automatically builds a set of documentation that you could, say, publish directly to a website. IDEs can also use them for tooltip popups. Generally, you want to write these like the reader won't have the actual code to read. Because they might not!

The second kind is standalone comments. They take up one or more lines all to themselves. I look at these like warning signs. When there's something about the upcoming chunk of code that doesn't tell the whole story obviously by itself. Perhaps something like:

/* The following code is written in a weird way on purpose.
I tried doing <obvious way>, but it causes a weird bug.
Please do not refactor it, it will break. */

Sometimes it's tempting to use a standalone comment to explain what dense, hard-to-read code is doing. But ideally, you'd want to shunt it off to a function named what it does instead, with a descriptive doc comment if you can't cram it all into a short name. Alternatively, rewrite the code to be less confusing. If you literally need the chunk of code to be in its confusing form, because a less confusing way doesn't exist or doesn't work, then this kind of comment explaining why is warranted.

The last kind are inline comments. More or less the same use case as above, the only difference being they appear on the same line as code, usually at the very end of the line:

dozen = 12 + 1; // one extra for the baker!

In my opinion, these comments have the least reason to exist. Needing one tends to be a signal of a code smell, where the real answer is just rewriting the code to be clearer. They're also a bit harder to spot, being shoved at the ends of lines. Especially true if you don't enforce maximum line length rules in your codebase. But that's mostly personal preference.

There's technically a fourth kind of comment: commented-out code. Where you select a chunk of code and convert it to a comment to "soft-delete" it, just in case you may want it later. I highly recommend against this. This is what version control software like Git is for. If you need it again, just roll back to it. Don't leave it to rot in your codebase taking up space in your editor and being an eyesore.

[-] flashgnash@lemm.ee 15 points 6 months ago* (last edited 6 months ago)

"tells the user the current time" would be an excellent comment for a clock

I'm not the best at commenting my code, but generally I just try to think of what information I'd want to know if looking at this 10 years from now

Imo comments are best used sparingly, don't bother commenting something that anyone with a basic understanding of programming would understand straight away by reading the code

Functions should generally be commented with what parameters are and what they're for, plus what they output

use reqwest::Client;

// create a http client class that all other files can import 
// so as to only create one instance globally 

pub struct HttpClient {
    client: Client,

}
impl HttpClient {
        pub fn new() -> Self {
            HttpClient {
                client: Client::new(),
            }
        }

        pub fn client(&self) -> &Client {
            &self.client

        }

}

Here's an example where if I were to stumble onto this file 10 years from now, I might think wtf is this looking at it out of context, the comment explains why it exists and what it's used for

(we'll ignore the fact I totally didn't just add this comment because I suck at commenting personal projects)

[-] jbrains@sh.itjust.works 11 points 6 months ago

Write comments that explain why the code isn't obvious just by reading it. Why did you do things the long way? What did you need to work around? Why didn't you do the thing that anyone reading the code would expect you to do?

Also write comments that explain the purpose of the functions you use, in case the names of those functions don't make it clear on their own.

[-] Dunstabzugshaubitze@feddit.org 10 points 6 months ago

the "what" is interesting on interfaces or when you generate documentation with some tool like sphinx or javadoc.

the "why" is interesting when you are somewhere inside a class or function and do something in a "strange" way, to work around a quirk in the codebase or something like that, or when you employ optimizations that make the code harder to read or atleast less obvious why somethings are done.

[-] marlowe221@lemmy.world 8 points 6 months ago

“Why” comments make more sense as application complexity grows.

You also have to consider interaction of the code with other external systems - sometimes external APIs force you to write code in ways you might not otherwise and it’s good to leave a trail for others on your team (and your future self…) about what was going on there.

[-] something_random_tho@lemmy.world 5 points 6 months ago

100%. I also like to leave comments on bug fixes. Generally the more difficult the fix was to find, the longer the comment. On a couple gnarly ones we have multiple paragraphs of explanation for a single line of code.

load more comments (2 replies)
[-] xmunk@sh.itjust.works 6 points 6 months ago

Not everything needs a comment - knowing when comments add value is the key... "what" vs "why" is usually a good indicator but some code just doesn't need a comment.

[-] darklamer@lemmy.dbzer0.com 3 points 6 months ago

Doesn't need any comment:

int getCount() { return count; }

Absolutely needs a very extensive comment:

double getBojangleFlux { return fubar * .42; }

[-] MotoAsh@lemmy.world 5 points 6 months ago* (last edited 6 months ago)

IMO, the most important parts are to document the actual intent of the code. The contract of what is being documented. Sure, it's only so useful in perfectly written code, but NO code is perfect, and few will come through later with full context already learned.

It makes it sooo mich easier to know what is intended behavior and what is an unchecked edge case or an unexpected problem. If it's a complicated thing with a lot of fallout, good documentation can save hours of manually lining up consequences and checking through them for sanity.

You might say, "but that's indication of bad code!". No. Not really. Consequences easily extend past immediate code doing things as trivial as saving data to the database without filtering, or having a publicly available service. Even perfectly coded things come up with vulnerabilities all the time due to underlying security issues. It's always great to have an immediate confirmation of what's supposed to happen whether it's immediate code or some library with a new quirk in a new version.

[-] firelizzard@programming.dev 4 points 6 months ago

My comment game has gotten far better since I started doing live code reviews. Essentially I ask myself, “Would I feel the need to explain this to someone during a code review?” and if the answer is yes I add a comment.

[-] QuazarOmega@lemy.lol 3 points 6 months ago* (last edited 6 months ago)

Making up an example on the spot is kinda difficult for me, but I'd look at it this way with a bold statement, you should hope that most code won't need comments. Let's exclude documentation blocks that are super ok to be redundant as they should give a nice, consistent, human readable definition of what x thing does (function, constant, enum, etc.) and maybe even how to use it if it's non-intuitive or there are some quirks with it.
After that, you delve in the actual meat of the code, there are ways to make it more self explanatory like extracting blocks of stuff into functions, even when you don't think it'll be used again, to be used with care though, as not to make a million useless functions, better is to structure your code so that an API is put into place, enabling you to write code that naturally comes out high level enough to be understood just by reading, this thing is very difficult for me to pinpoint though, because we think of high level code as abstractions, something that turns the code you write from describing the what rather than the how, but really, it's a matter of scope, a print statement is high level if the task is to print, but if the task is to render a terminal interface then the print becomes low level, opposite is also true, if you go down and your task is to put a character onto stdout, then the assembly code you'd write might be high level. What I mean to say is that, once you have defined the scope, then you can decide what level of knowledge to expect of the reader when looking at your code, from there, if some process feels fairly convoluted, but it doesn't make sense to build an abstraction over it, then it is a good place to put a comment explaining why you did that, and, if it's not really clear, even what that whole block does

load more comments (6 replies)
load more comments (2 replies)
[-] lnxtx@feddit.nl 19 points 6 months ago

Self-explainable, when you aren't writing spaghetti Perl scripts.

[-] Swedneck@discuss.tchncs.de 16 points 6 months ago* (last edited 6 months ago)

//forgive my sins, it took me 2 hours to nail down this arcane spell. if anyone touches this they will know my wrath
=(/&)((//((%=)(&)%)(&()

[-] Underwaterbob@lemm.ee 14 points 6 months ago

I like to include profanity in all my comments for spiciness.

[-] GooberEar@lemmy.wtf 12 points 6 months ago

I know some folks are joking about and dunking on this, but in modern times, I have justification. Call me lazy, but I have found myself writing out these comments and then letting the AI take over to at least give me a sketch of an implementation. Works reasonably well and saves me a lot of time and effort. Mostly I don't bother to remove them, though I usually edit them a bit.

On the other hand, there are factions within my colleagues who steadfastly insist that commenting is unnecessary and to some degree even potentially harmful, and that if you feel the need to comment your code, it means your code should be improved so that it's obvious what it is doing without the need for comments.

[-] Benjaben@lemmy.world 5 points 6 months ago

Would you mind sharing a bit more about the workflow you're describing? I'm on a "ask people how they're using AI to help them dev" kick.

Sounds like you're using an agent integrated with your IDE, would you be willing to give specifics? And you're talking about writing some comments that describe some code you haven't yet written, letting the AI take a stab at writing the code based on your comments, and then working from there? Did I get that right?

Happy for literally any elaboration you feel like giving :)

[-] GooberEar@lemmy.wtf 3 points 6 months ago* (last edited 6 months ago)

I use VS Code and GitHub Co-pilot and develop in a variety of different languages and frameworks. I've got lots of experience with some, but I'm less knowledgeable on others.

So, having the AI assist with languages I am very familiar with is basically a way to save time and preserve my mental energy. For languages and frameworks I'm less experienced with, it speeds things up because I'm not having to constantly search how-tos and forums for guidance. And for languages/frameworks I have limited or no experience with, it can be a helpful learning tool that speeds up how long it takes to get ramped up.

With this set-up, if I start writing a line of code and then pause for a moment, co-pilot kicks in and tries to autocomplete that line, sometimes even suggests the entire block of code. It's really good at recognizing simple patterns and common boilerplate stuff. It's less good at figuring out more complex stuff, though.

However, I find that if I start out by writing a comment that explains what I'm trying to accomplish, and to some degree how to accomplish it before I start writing one of those more complex blocks/lines, the AI has a much higher success rate in returning helpful, functioning code. So, basically yes, I write the comment to describe code I haven't written, and I'll let the AI take over from there.

This works for code, raw database queries, configuration files, and even for writing tests. I'm not an expert at building out Docker configurations for local development or configuring auto-deployment on whatever random system is being used for a project, but I can often get those things up and running just by describing in comments what I need and what I'm trying to accomplish.

The VS Code co-pilot extension also has some context menu items that let you ask questions and/or ask for suggestions, which comes in handy for some things, but for me, typing out my intentions in comments and then letting the auto-complete kick in as I'm starting a line of code is faster, more efficient, and seems to work better.

Granted, co-pilot also likes to try to auto-complete comments, so that's sometimes funny just to read what it "thinks" I'm trying to do. And most of the time, I do remove my comments that were specifically to guide co-pilot on what I wanted it to do if they're super redundant. And, at the end of the day, not everything co-pilot suggests is production-worthy, functional, nor does what I actually described. In fact, a lot of it is not, so you should expect to go back and fine tune things at a minimum. It's just that overall, it's good enough that even with all the supervision and revisions I have to make, it's still a net positive, for now.

load more comments (1 replies)
[-] parpol@programming.dev 4 points 6 months ago* (last edited 6 months ago)

At least docblocking a summary above every method is always good. You can automatically generate documentation this way.

[-] figaro@lemdro.id 9 points 6 months ago

Made a comment

[-] linkhidalgogato@lemmy.ml 8 points 6 months ago

basically how it feel when a professor requires u comment every single line of code u write to explain it. I know people tend to drop out of real engineering to do programing but an entire 4 years of this bullshit as opposed to just a couple classes sounds way worse than calc 3 or differential equations.

load more comments (3 replies)
[-] TootSweet@lemmy.world 7 points 6 months ago

We have to go deeper.

[-] style99@lemm.ee 6 points 6 months ago

A true Klingon never uses comments.

[-] marlowe221@lemmy.world 6 points 6 months ago

Glory to you and your house!

[-] iAvicenna@lemmy.world 4 points 6 months ago

the church of uncle bob would like to speak to you about the sins of commenting.

load more comments (1 replies)
load more comments
view more: next ›
this post was submitted on 28 Sep 2024
1166 points (100.0% liked)

Programmer Humor

34854 readers
412 users here now

Post funny things about programming here! (Or just rant about your favourite programming language.)

Rules:

founded 5 years ago
MODERATORS