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.
the variables were not defined properly and were named esoterically
I wonder why it was so hard and took so long to write
Poor skill, mostly.
As demonstrated by the variable naming and documentation.
Oof!
Int ajdixneh = fuckyouandthisjob;
At what point is documenting decompiled code easier?
Me: “haha…no” proceeds to delete function “whoever wrote this can figure it out again.”
$ mysterytool $WHAT DID YOU DO?!
$ mysterytool -vv DEBUG: Complete. $Knowing my luck, It probably deleted a rarely used system library and will lead to unpredictable crashes.
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
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.
Even on simple scripts, it’s so help to remind yourself however the hell you made it work.
I always document a lot because I forget what I was doing one week after.
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.
bc everyone is a gamer, and using another chatting app is just adding more clutter
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 :)
Easy: people who still use Discord have brain rot
Why?
i wrote poorly documented code on my solo projects because i am lonely
I write buggy software so that users will email me.
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 think it’s loneliness, honestly.
That and corporate work environment tends to rewards those that can explain stuff vocally ad nauseum.
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?”
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
Did they at least provide woman pages then?
/s
I’ve only known about (and always use) xclip.
copyq — if anyone needs universal multiplatfom gui app
Be the change you want to see in the world and create a PR. 😃
tbf syntax for writing manpages is closer to latex than markdown
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
Soy devs have invaded Linux.
What do you mean by this?
“You’re not a real dev if don’t know [insert thing here]”
I’m not seeing the soy connection
It’s a derivative of https://en.wikipedia.org/wiki/Soy_boy
Haha, I made this :) Here’s the blog post I created it for, if you want a bit of context:
Correct, I shamelessly stole it!
Also, sorry, I stole it.
No worries :)
But also
mysterytool --help
mysterytool: unrecognized option: '-'ok then…
mysterytool -h
mysterytool: unrecognized option: 'h'mysterytool --help ‘--help’ unrecognized option, -h for helpI will burn this motherfucker to the ground
Or the opposite:
mysterytool -h -h unrecognized option, --help for helpBoth need to burn.
Sometimes
mysterytool -Hworksmysterytool -haaaaaalpSome 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.
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 youIf I can’t get it with
tldr mysterytoolafter all that, then clearly the developer intended it to stay a mystery.strings mysterytoolAs a last resort haha
It could be worse. The documentation could be online, only accessible through a paywall.
Okay, Oracle.
Oh, they do it, too?
If the program’s author hasn’t bothered to properly document its function, then it has no business being on my machine.
“tHe PrOgRaM iS sElF dOcUmEnTiNg”
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 🤷🏻♂️
Hack the planet!
If it is open source, you can read the source…
Or he can waste less time and download a properly documented open source tool.
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.
I never understood that. I’m a programmer and I tend to over-document.
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.
I like to think most of us grow out of it.
I like to think most of us grow out of it.
Morgan Freeman: “But they didn’t”
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.
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.
No idea why’d anyone would do this if they expected anyone besides them to use their tool.
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
It’s like people don’t like surprises anymore.
Embedded *nix be like
Cries in busybox
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.
Legacy *nix vendor tools be like
Exclusively installed through some dodgy PPA you got from a blog.
strings `which mysterytool` | lessGive up your darn secrets before I start fumbling around with
straceand get even more frustrated!I just want to say this is a masterful use of the format.
I’d try
mysterytool -H-H for Hard drive to delete, -h is help
-H is for Hforce
-his halt.Which assumes you also wanted to catch fire because you didn’t set
--halt-without-catching-fireDo 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--infosudo shutdown -h nowIt makes sense in context. Whaddya gonna do?
-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.
