• 0 Posts
  • 15 Comments
Joined 2 months ago
cake
Cake day: August 15th, 2024

help-circle
  • pixelscript@lemm.eetoProgrammer Humor@lemmy.mlComenting code
    link
    fedilink
    English
    arrow-up
    21
    ·
    edit-2
    9 days 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.


  • Fellow tattooless here. Uh, neither?

    I simply don’t see the appeal of putting on something I can’t easily take off if I wanted to, for its own sake. Yeah, tattoos aren’t permanent, a removal process exists. But they cost money and require an appointment to be rid of, on top of the investment of time, money, and pain to buy in. The barrier to entry and the barrier to exit are both too high for my liking.

    Ideally you get a tattoo and enjoy it for life. I can’t commit to that kind of decision. Not for a funny body picture. If I need a memento to cherish memory of a thing or event I’ll get a tchotchke or something.

    I have no complaints about others’ tattoos. They’re more often than not incredible works of art.


  • There are exactly three kinds of manpages:

    1. Way too detailed
    2. Not nearly detailed enough
    3. There is no manpage

    I will take 1 any day over 2 or 3. Sometimes I even need 1, so I’m grateful for them.

    But holy goddamn is it awful when I just want to use a command for aguably its most common use case and the flag or option for that is lost in a crowd of 30 other switches or buried under some modal subcommand. grep helps if you already know the switch, which isn’t always.

    You could argue commands like this don’t have “arguably most common usecases”, so manpages should be completely neutral on singling out examples. But I think the existence of tl;dr is the counterargument.

    Tangent complaint: I thought the Unix philosophy was “do one thing, and do it well”? Why then do so many of these shell commands have a billion options? Mostly /s but sometimes it’s flustering.



  • pixelscript@lemm.eeto196@lemmy.blahaj.zoneAutism rule
    link
    fedilink
    English
    arrow-up
    1
    ·
    1 month ago

    Yes. On average.

    If you specifically take 100 kilos of core material from the Sun, then it would be a no contest victory for the Sun. But the Sun is very, very big, and when it comes to producing energy, most of it is doing absolutely nothing. So it brings the average energy production per kilo way, way down.




  • pixelscript@lemm.eeto196@lemmy.blahaj.zoneAutism rule
    link
    fedilink
    English
    arrow-up
    3
    ·
    1 month ago

    On the other hand, if you average the Sun’s energy generation across its entire volume and adjust for that volume’s mass, an equivalent mass of human body tissue generates more heat energy.

    So your eyes may not have the raw lumen output of an entire star; but, pound for pound, your eyes would outshine a similarly massive piece of one.





  • Kind of a lame example that depending on who you are may make you go, “Uhh… yeah? Duh?” but…

    Y’know how Hollywood has been using the same library of stock sounds for like half a century? Wilhelm scream tier stuff? Like, if I had a nickel for every time I’ve heard one of those stock baby noises, or that ape screeching, you know the ones, I’d have a good chunk of change by now.

    And if you ever encounter real world examples of some of these things, they never sound quite like those recordings. This is in large part because Hollywood loves pairing sounds of specific creatures or objects with footage of completely different creatures or objects that in reality sound nothing like that (e.g. no, bald eagles do not make that noise at all). So these sounds become reified in your head as “the sounds fake shit in movies make”. The acoustic equivalent of what fruit flavored candies are to actual fruits. Does that make sense?

    All this to say, it’s really disorienting when you encounter things in the real world that actually make these noises. Particularly if you aren’t regularly used to being around them.

    For me in particular, it’s roosters and horses. My mind is conditioned to assume that the stock noises for these creatures I hear in films and the like are, I dunno, extremely cherry-picked noises from some specific breed or species of the animal that aren’t the ones I’d commonly find around me. Not the case! They really do sound like that! To a spookily accurate degree, too. Being around them feels like someone is pranking me with a soundboard, I almost can’t believe it’s real.

    It’s a bit depressing that sound design of film has disillusioned me to the point I’m shocked to hear that roosters in real life actually sound like roosters in movies and on TV, but nonetheless here we are.


  • For me, multimedia is a non-negotiable part of the web experience.

    Yes, I get as annoyed as the next guy when I want, say, a simple tutorial written in a couple paragraphs, but the only ones anyone seem to want to make are eight minute long videos filled with fluff. That sucks. But purposefully excluding it from your protocol because it burned you a fee times is a gross overcorrection in my view.

    I appreciate the Gemini project, I respect its goals, and I am happy that it meets the needs of several people such as yourself. But for me, and I think for a great majority of people who would be potentially interested in its broader goal of simplifying the web but are dealbroken by lack of multimedia capabilities, Gemini will never be anything more than a toy. A quirky little curiosity that will never expand beyond a tiny clique of people who accept Gemini for what it is and are content to only ever see content from that same small pool of people.



  • pixelscript@lemm.eetoMemes@lemmy.mlZen Z
    link
    fedilink
    English
    arrow-up
    2
    arrow-down
    1
    ·
    edit-2
    2 months ago

    An analog clock is just three sets of loading bars with their ends glued together. You can tell geometrically what proportion of each division of time (day, hour, and minute) are spent and what proportion remains. You don’t even need the numbers.

    If you need stopwatch-level precision, sure, a digital display is superior. But how often do you need that? Most of what I need clocks for is, “Oh, it’s about a quarter to noon, I have a lunch appointment to get to”.

    It is my personal preference to visually intuit that the clock hands are roughly separating the hour into 3/4 spent and 1/4 remaining and use that to know how much time I have left to the hour, rather than read the symbols “42” on the display and manually do the mental gymnastics of “well that’s basically 45, which is three quarters of the way to 60 minutes”.

    I’ll admit this benefit is marginal.