• oleorun@real.lemmy.fan
    link
    fedilink
    English
    arrow-up
    140
    ·
    1 year ago

    Reminds me of a comment I once came across in a work application’s code: “This function took forever to write correctly. It was hard work. I didn’t document it. Figure it out.”

    Of course the variables were not defined properly and were named esoterically.

  • clearleaf@lemmy.world
    link
    fedilink
    arrow-up
    101
    arrow-down
    1
    ·
    edit-2
    1 year ago

    I don’t understand how devs can be too lazy to write documentation but somehow they’d rather explain the same shit in discord over and over and over and over and over and over

    • RoyaltyInTraining@lemmy.world
      link
      fedilink
      arrow-up
      50
      ·
      1 year ago

      The help command is one of the first things I work on in any project. Even if I’m never gonna share it, my future self will appreciate it.

      • kurwa@lemmy.world
        link
        fedilink
        arrow-up
        9
        ·
        1 year ago

        Even on simple scripts, it’s so help to remind yourself however the hell you made it work.

    • Rooty@lemmy.world
      link
      fedilink
      arrow-up
      42
      ·
      edit-2
      1 year ago

      Why is discord so popular in non-gaming circles? People use it as a shitty, bloated and centralized IRC clone, with the voice fuction being completely ignored.

      • oldfart@lemm.ee
        link
        fedilink
        arrow-up
        1
        ·
        1 year ago

        I’m no discord fan but my recent attempts with using IRC failed because I had incorrect reverse dns or some shit like that. Obviously I have no control over that in a consumer connection.

        There are still better alternatives than Discord, though :)

    • peopleproblems@lemmy.world
      link
      fedilink
      arrow-up
      9
      ·
      1 year ago

      I think it’s loneliness, honestly.

      That and corporate work environment tends to rewards those that can explain stuff vocally ad nauseum.

    • hperrin@lemmy.world
      link
      fedilink
      arrow-up
      7
      ·
      1 year ago

      As someone who writes fairly extensive documentation, I can assure you that it doesn’t matter. People will still ask questions in your Discord that are answered in your documentation.

      I’ve learned that you kind of have to strike a balance between being terse enough that people will read it and verbose enough that it’s actually helpful, but there is a minimum number of questions you will always get.

    • Treczoks@lemmy.world
      link
      fedilink
      arrow-up
      3
      ·
      1 year ago

      At work, I am one of the few who actually documents. Not only with Doxygen, but I also write real documents regarding all kinds of topics.

      Guess what? “I know you have this documented somewhere, but could you just quickly explain again how this common task works?”

  • Navigate@partizle.com
    link
    fedilink
    English
    arrow-up
    83
    ·
    edit-2
    1 year ago

    I was recently trying trying to get help on a clipboard program someone had recommended me, clipq. What I found instead was a GitHub discussion where the dev said “I’m not sure what you mean by ‘man’ pages” in response to someone asking for them. I think I need to find an alternative

  • qupada@kbin.social
    link
    fedilink
    arrow-up
    48
    ·
    1 year ago

    But also

    mysterytool --help
    mysterytool: unrecognized option: '-'

    ok then…

    mysterytool -h
    mysterytool: unrecognized option: 'h'

  • Rooty@lemmy.world
    link
    fedilink
    arrow-up
    43
    arrow-down
    1
    ·
    1 year ago

    If the program’s author hasn’t bothered to properly document its function, then it has no business being on my machine.

      • taladar@sh.itjust.works
        link
        fedilink
        arrow-up
        3
        ·
        1 year ago

        That claim doesn’t even work for the 0 line shell script that used to be /bin/true (which is why it is no longer a 0 line shell script), much less any more complicated program.

      • sheogorath@lemmy.world
        link
        fedilink
        arrow-up
        1
        arrow-down
        1
        ·
        1 year ago

        Fuck those people, people who says that usually doesn’t even understand half the time. When I ask people like that when they write a functionality a certain way during code review usually they’ll just quote someone on Twitter or some blogspam article saying A is shit, B is the best way to do things.

        • AnIntenseMoist@lemmy.world
          link
          fedilink
          arrow-up
          1
          arrow-down
          1
          ·
          1 year ago

          you forget StackOverflow. I saw my coworker once copy-and-paste code… from the question… and not understand why it wasn’t working… I’m all for using StackOverflow to get help with weird problems but, most of the time, simply reading the docs and applying that knowledge to the problem you are trying to solve is enough. a forgotten art for sure…

      • Draconic NEO@lemmy.world
        link
        fedilink
        arrow-up
        4
        ·
        edit-2
        1 year ago

        Only if the source is structured and has readable names. Spaghetti code with made up variable names that only the programmer knows the meaning of (or may not even remember what they mean at all) isn’t that much better than combing through the disassembled machine code.

      • Treczoks@lemmy.world
        link
        fedilink
        arrow-up
        2
        ·
        1 year ago

        Which is fine for a.small and simple tool. But I have seen massive graphic/UI libraries with a documentation of about two pages and a non-working example.

        Worst offenders I have to deal with is mediawiki. Some random hacker replaces some code with his own, and immeditely obsoletes the previous code that worked absolutely fine. The new code might work, too, but the concept, the philosophy is 100% different that the old interface. So e.g. the old interface made a call with 10 or 20 parameters, the new one makes a ton of calls of the type “add one or two parameters to an object”.

        And of course the only documentation is just the excrement of a Doxygen call. Where nobody ever cared for the function description headers in the source.

        My “favourite” one is a function with a parameter named “options” and a description as “option flags”. Nothing more. And the source of the function? Well, I have seen staighter spaghetti dinners.

  • Aceticon@lemmy.world
    link
    fedilink
    arrow-up
    33
    arrow-down
    1
    ·
    edit-2
    1 year ago

    Programmers generally detest to do documentation, so when the user help “UI” is all down to a programmer to define this is often what you get, especially if it’s a small tool.

    • pomodoro_longbreak@sh.itjust.works
      link
      fedilink
      arrow-up
      16
      ·
      1 year ago

      Yeah this is shitty, and if you’re a programmer reading this and you agree with it, be better. There is no excuse for under-documenting a CLI.

      Even when I’m developing, I write out my usage text first, like -o [json,csv,pretty] specify output format (default 'pretty') [NOT IMPLEMENTED] or the like.

    • Aceticon@lemmy.world
      link
      fedilink
      arrow-up
      6
      ·
      edit-2
      1 year ago

      Speaking for myself a long time ago when I was younger and handsomer but dumber ;) some people at a certain stage of their lives have trouble remembering that what’s obvious for oneself given the context one is in and the information one has, is not obvious for others.

      I like to think most of us grow out of it.

    • taladar@sh.itjust.works
      link
      fedilink
      arrow-up
      5
      ·
      1 year ago

      If you use something like Rust’s clap --help output is very easy to add, all you need is basically a single line comment for each option.

      • Aceticon@lemmy.world
        link
        fedilink
        arrow-up
        15
        arrow-down
        2
        ·
        edit-2
        1 year ago

        Oh, you sweet summer child, there is no level of ease for the average programmer that will make him or her want to document things… ;)

        On a more serious note, good documentation for parameters in any tool that’s not stupidly simple tends to be more than a one liner if one doesn’t assume that the user already knows a ton of context (for example, imagine explaining “chmod” parameters with just one liners)

        • taladar@sh.itjust.works
          link
          fedilink
          arrow-up
          2
          ·
          1 year ago

          You can write more than one line but one line is usually enough for each of the options in the --help output. Obviously that doesn’t explain everything and especially not background like “how do unix permissions work” in your example but the --help output is not the correct place for that kind of information anyway.

          • Aceticon@lemmy.world
            link
            fedilink
            arrow-up
            2
            ·
            edit-2
            1 year ago

            The point is that a programmer would first need to think about what needs to be explained or not to the average user and then explain it properly, none of which is considered as interesting as coding.

            It’s not by chance that even tools with actual one line of explanation for each parameter are general of the badly documented kind (I especially like the ones were the “help” for a command doesn’t say what the bloody command actually does).

            I mean, you even see this kind of meaningless “documentation” in API documentation for widelly used libraries were the documentations is generated from comments embedded in the code: “public void doStuff(int height)” => “Does stuff. Parameters - height: the input height”.

            I might have put it in a humouristic way but this quite a well-known and widespread phenomenon.

      • hikaru755@feddit.de
        link
        fedilink
        arrow-up
        1
        ·
        edit-2
        1 year ago

        Even I myself am not gonna remember how to use my tool a couple months down the line, unless it’s something I use very regularly.

        Edit: noticed I read the comment I’m replying to wrong, reworded to make more sense

  • kshade@lemmy.world
    link
    fedilink
    English
    arrow-up
    25
    ·
    edit-2
    1 year ago

    strings `which mysterytool` | less

    Give up your darn secrets before I start fumbling around with strace and get even more frustrated!

        • droans@lemmy.world
          link
          fedilink
          arrow-up
          1
          ·
          1 year ago

          Do developers get hard-ons for using nonstandard flags?

          Use -h, --help. None of this “no hyphen” bullshit or using the plus sign or a different flag like --info

      • corsicanguppy@lemmy.ca
        link
        fedilink
        arrow-up
        2
        arrow-down
        1
        ·
        1 year ago

        -H is for “hell no just uninstall”

        Look, if they can’t stick to established convention and they’re not gnu (and thus magically excusably arrogant as fuck because #stallman), then you just know they’ll be somehow dragging in remote libraries or something equally as fuckwitted; so just remove it and live your life.