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.
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
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.
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 :)
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.
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
It is not that complicated and there are plenty of tools to generate man pages from other formats. Besides, this is about the dev not knowing what a man page even is.
Stuff like this is why I'm really glad I was a hard ass about learning "the right way," and refused to let myself use a full IDE and instead rely on a terminal setup. Crazy how many people (with tons of experience) can be missing basic knowledge about how *nix environments run
I can't imagine working with linux and not being comfortable with its most fundamental conceit: interactive ttys that you can do anything from. It's like being a Windows user and not knowing about the Start menu
Some of the older programs and scripts I've seen in the codebases I help maintain have -u or -?. If I have an excuse to do any changes to them I'll usually change them to use -h and --help.
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.
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.
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.....
I'd pretend to be Joey from Hackers and just throw commands at it to see what happens. Maybe I'll make an ATM in bumfuck, Egypt spit out hundreds of dollars or find a worm in a garbage file 🤷🏻♂️
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.
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.
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.
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.
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.
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)
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.
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.
That, at least, had an excuse to be terse. If you use busybox, you probably have a real machine with the ability to browse the online documentation, anyway.
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.
115 Comments
oleorun@real.lemmy.fan · 141 pts · 2y
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.
BleatingZombie@lemmy.world · 109 pts · 2y
I wonder why it was so hard and took so long to write
oleorun@real.lemmy.fan · 32 pts · 2y
Poor skill, mostly.
corsicanguppy@lemmy.ca · 11 pts · 2y
As demonstrated by the variable naming and documentation.
BleatingZombie@lemmy.world · 1 pts · 2y
Oof!
nobleshift@lemmy.world · 34 pts · 2y
spacesweedkid27@lemmy.world · 12 pts · 2y
At what point is documenting decompiled code easier?
rwhitisissle@lemmy.world · 4 pts · 2y
Me: "haha...no" proceeds to delete function "whoever wrote this can figure it out again."
Perroboc@lemmy.world · 136 pts · 2y
WHAT DID YOU DO?!
hperrin@lemmy.world · 41 pts · 2y
RoyaltyInTraining@lemmy.world · 34 pts · 2y
Knowing my luck, It probably deleted a rarely used system library and will lead to unpredictable crashes.
clearleaf@lemmy.world · 100 pts · 2y
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 · 51 pts · 2y
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 · 9 pts · 2y
Even on simple scripts, it's so help to remind yourself however the hell you made it work.
oce@jlai.lu · 5 pts · 2y
I always document a lot because I forget what I was doing one week after.
Rooty@lemmy.world · 43 pts · 2y
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.
dym_sh@lemmy.world · 9 pts · 2y
bc everyone is a gamer, and using another chatting app is just adding more clutter
oldfart@lemm.ee · 1 pts · 2y
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 :)
pimento64@sopuli.xyz · 11 pts · 2y
Easy: people who still use Discord have brain rot
lud@lemm.ee · 1 pts · 2y
Why?
MonsiuerPatEBrown@reddthat.com · 11 pts · 2y
i write poorly documented code on my solo projects because i am lonely
Agent641@lemmy.world · 8 pts · 2y
I write buggy software so that users will email me.
peopleproblems@lemmy.world · 9 pts · 2y
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 · 7 pts · 2y
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 · 3 pts · 2y
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 · 83 pts · 2y
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
kamen@lemmy.world · 25 pts · 2y
Did they at least provide woman pages then?
/s
Giftzwerg02@lemmy.world · 10 pts · 2y
I've only known about (and always use) xclip.
dym_sh@lemmy.world · 2 pts · 2y
copyq — if anyone needs universal multiplatfom gui app
raldone01@lemmy.world · 7 pts · 2y
Be the change you want to see in the world and create a PR. 😃
dym_sh@lemmy.world · 5 pts · 2y
tbf syntax for writing manpages is closer to latex than markdown
taladar@sh.itjust.works · 14 pts · 2y
It is not that complicated and there are plenty of tools to generate man pages from other formats. Besides, this is about the dev not knowing what a man page even is.
tdawg@lemmy.world · 3 pts · 2y
Stuff like this is why I'm really glad I was a hard ass about learning "the right way," and refused to let myself use a full IDE and instead rely on a terminal setup. Crazy how many people (with tons of experience) can be missing basic knowledge about how *nix environments run
pomodoro_longbreak@sh.itjust.works · 2 pts · 2y
I can't imagine working with linux and not being comfortable with its most fundamental conceit: interactive ttys that you can do anything from. It's like being a Windows user and not knowing about the Start menu
pascal@lemm.ee · -1 pts · 2y
Soy devs have invaded Linux.
pomodoro_longbreak@sh.itjust.works · 5 pts · 2y
What do you mean by this?
kautau@lemmy.world · 9 pts · 2y
"You're not a real dev if don't know [insert thing here]"
pomodoro_longbreak@sh.itjust.works · 2 pts · 2y
I'm not seeing the soy connection
kautau@lemmy.world · 4 pts · 2y
It’s a derivative of https://en.wikipedia.org/wiki/Soy_boy
Xophmeister@lemmy.world · 64 pts · 2y
Haha, I made this :) Here’s the blog post I created it for, if you want a bit of context:
https://www.tweag.io/blog/2023-10-05-cli-ux-in-topiary/
crispy_kilt@feddit.de · 9 pts · 2y
Correct, I shamelessly stole it!
Also, sorry, I stole it.
Xophmeister@lemmy.world · 4 pts · 2y
No worries :)
qupada@kbin.social · 49 pts · 2y
But also
mysterytool --helpmysterytool: unrecognized option: '-'ok then...
mysterytool -hmysterytool: unrecognized option: 'h'NegativeLookBehind@kbin.social · 40 pts · 2y
I will burn this motherfucker to the ground
Melody@lemmy.one · 15 pts · 2y
Or the opposite:
Both need to burn.
lud@lemm.ee · 1 pts · 2y
Sometimes
mysterytool -HworksNegativeLookBehind@kbin.social · 4 pts · 2y
mysterytool -haaaaaalpiguessthislldo@lemmy.world · 1 pts · 2y
Some of the older programs and scripts I've seen in the codebases I help maintain have
-uor-?. If I have an excuse to do any changes to them I'll usually change them to use-hand--help.corsicanguppy@lemmy.ca · 26 pts · 2y
And
mysterytool -hmysterytool: try our info page that requires a custom viewer because gnu is better than standards. And there is no regular man page because fuck youcyanarchy@sh.itjust.works · 8 pts · 2y
If I can't get it with
tldr mysterytoolafter all that, then clearly the developer intended it to stay a mystery.dgriffith@aussie.zone · 7 pts · 2y
As a last resort haha
Treczoks@lemmy.world · 2 pts · 2y
It could be worse. The documentation could be online, only accessible through a paywall.
droans@lemmy.world · 3 pts · 2y
Okay, Oracle.
Treczoks@lemmy.world · 1 pts · 2y
Oh, they do it, too?
Rooty@lemmy.world · 42 pts · 2y
If the program's author hasn't bothered to properly document its function, then it has no business being on my machine.
AnIntenseMoist@lemmy.world · 30 pts · 2y
"tHe PrOgRaM iS sElF dOcUmEnTiNg"
taladar@sh.itjust.works · 3 pts · 2y
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 · 0 pts · 2y
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 · 0 pts · 2y
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.....
Kolanaki@yiffit.net · 6 pts · 2y
I'd pretend to be Joey from Hackers and just throw commands at it to see what happens. Maybe I'll make an ATM in bumfuck, Egypt spit out hundreds of dollars or find a worm in a garbage file 🤷🏻♂️
PainInTheAES@lemmy.world · 3 pts · 2y
Hack the planet!
topinambour_rex@lemmy.world · -3 pts · 2y
If it is open source, you can read the source...
Darkhoof@lemmy.world · 12 pts · 2y
Or he can waste less time and download a properly documented open source tool.
Draconic_NEO@lemmy.world · 4 pts · 2y
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 · 2 pts · 2y
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.
AnUnusualRelic@lemmy.world · 32 pts · 2y
It's like people don't like surprises anymore.
Aceticon@lemmy.world · 32 pts · 2y
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.
isVeryLoud@lemmy.ca · 22 pts · 2y
I never understood that. I'm a programmer and I tend to over-document.
BlueKey@kbin.social · 14 pts · 2y
the messiah
pomodoro_longbreak@sh.itjust.works · 16 pts · 2y
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 · 6 pts · 2y
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.
EuroNutellaMan@lemmy.world · 4 pts · 2y
Morgan Freeman: "But they didn't"
taladar@sh.itjust.works · 5 pts · 2y
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 · 13 pts · 2y
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 · 2 pts · 2y
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 · 2 pts · 2y
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.
mojo@lemm.ee · 3 pts · 2y
No idea why'd anyone would do this if they expected anyone besides them to use their tool.
hikaru755@feddit.de · 1 pts · 2y
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
SpaceNoodle@lemmy.world · 32 pts · 2y
Embedded *nix be like
lemming741@lemmy.world · 12 pts · 2y
Cries in busybox
Treczoks@lemmy.world · 5 pts · 2y
That, at least, had an excuse to be terse. If you use busybox, you probably have a real machine with the ability to browse the online documentation, anyway.
seaQueue@lemmy.world · 8 pts · 2y
Legacy *nix vendor tools be like
anarchy79@lemmy.world · 27 pts · 2y
Exclusively installed through some dodgy PPA you got from a blog.
kshade@lemmy.world · 25 pts · 2y
strings `which mysterytool` | lessGive up your darn secrets before I start fumbling around with
straceand get even more frustrated!TheHighRoad@lemmy.world · 22 pts · 2y
I just want to say this is a masterful use of the format.
Inductor@feddit.de · 14 pts · 2y
I'd try
mysterytool -HBeardedGingerWonder@feddit.uk · 35 pts · 2y
-H for Hard drive to delete, -h is help
caseyweederman@lemmy.ca · 7 pts · 2y
-H is for Hforce
hperrin@lemmy.world · 5 pts · 2y
-his halt.cyanarchy@sh.itjust.works · 9 pts · 2y
Which assumes you also wanted to catch fire because you didn't set
--halt-without-catching-firedroans@lemmy.world · 1 pts · 2y
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--infohperrin@lemmy.world · 2 pts · 2y
It makes sense in context. Whaddya gonna do?
corsicanguppy@lemmy.ca · 1 pts · 2y
-His 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.
TunaCowboy@lemmy.world · 10 pts · 2y
Use the Source, Luke!
captainWhatsHisName@lemm.ee · 10 pts · 2y
jbk@discuss.tchncs.de · 21 pts · 2y
rm $(which mysterytool)?_dev_null@lemmy.zxcvn.xyz · 6 pts · 2y
What if that returns just an alias?
But really the best way would be first to try one's distro manager to uninstall/purge the package. Unless it was just manually installed by the user.
Oh, maybe that's it! It only exists in
~/bin, and OP is having a psychotic break, is just now finding out about their split personality!lolcatnip@reddthat.com · 3 pts · 2y
Use
+;\;is for peasants.crispy_kilt@feddit.de · 3 pts · 2y
Y u no
-deleteHonytawk@lemmy.zip · 9 pts · 2y
Quite the mystery!
_dev_null@lemmy.zxcvn.xyz · 9 pts · 2y
python -VWhat the actual fuck
30mag@lemmy.world · 9 pts · 2y
synae@lemmy.sdf.org · 3 pts · 2y
It does one thing and it does it well
cyanarchy@sh.itjust.works · 1 pts · 2y
Confuse the system operator?
synae@lemmy.sdf.org · 1 pts · 2y
If the mysterytool is not confusing, the operator ought to file a bug
droans@lemmy.world · 9 pts · 2y
What's worse is when the tool doesn't error out for providing bad flags. And it always seems like those same tools always use nonstandard flags.
spacesweedkid27@lemmy.world · 8 pts · 2y
joyjoy@lemm.ee · 10 pts · 2y
Johanno@feddit.de · 10 pts · 2y
spacesweedkid27@lemmy.world · 5 pts · 2y
If that does not work, then sending death threats to the devs might.
nevemsenki@lemmy.world · 2 pts · 2y
Isn't that what Bard is for?
Klaymore@sh.itjust.works · 4 pts · 2y
tldr mysterytoolcrispy_kilt@feddit.de · 1 pts · 2y
No one uses
infoKISSmyOS@lemmy.world · 6 pts · 2y
corsicanguppy@lemmy.ca · 2 pts · 2y
sudo rpm -ef $(which mysterytool)pomodoro_longbreak@sh.itjust.works · 5 pts · 2y
mysterytool: nothing appropriate.
cupcakezealot@lemmy.blahaj.zone · 4 pts · 2y
the monty hall function
Artyom@lemm.ee · 3 pts · 2y
Apple moment
datelmd5sum@lemmy.world · 2 pts · 2y
grep -ir *mystery* /*