I am being a good little programmer and adding docstrings to some Elixir code. I hate looking at it. It so gets in the way of the code; see below.
I want an #emacs keypress that hides all lines between two regexps (One for @…doc…”””; one for the ending “””.) Weirdly, I can’t find anything. I used to be good at Elisp/Emacs programming, but I pretty much stopped doing that around 30 years ago. So looking for something similar I can hack on (or package that obviates the need to).
P.S. It’s my opinion that docstrings were a mistake. I imagine there was some hope that putting them next to the code they describe would help them stay up-to-date, but I am unconvinced they do. It’d be better to have a separate file which you’d bring up / jump to just like your editor lets you jump-to-definition. You don’t want to read the unformatted docstring anyway.
@marick I am mostly pleased with the XML Doc Comments in C# because the compiler (and the IDE, in real time) can tell you when you're missing things (like an undocumented parameter) or screwing things up (like documenting a parameter that doesn't exist). Not perfect, but I wouldn't want it to live somewhere else just because I like the proximity to the signature to see the issues in real time.
@marick For a long time I have been and continue to be conflicted about internal documentation. Where I have landed is similar to unit tests. It may be worth doing well, with full team buy-in, but it isn't worth the effort in any other circumstance.
Its greatest value is after a full team turnover, or when a codebase is in "maintenance mode." But that is also the time when you should assume the worst and not trust it at face value.
I still favor the Extreme Programming position that comments other than "why" should be eliminated by improving the code such that they are no longer needed.
With an exception for "public APIs," consumed by others, who may not have access to your source code and tests.
@JeffGrigg@marick I agree... So long as the team can come to an agreement on what code looks like that doesn't need comments. I have a strong opinion, but am not convinced this is an objective thing.
@cammerman@JeffGrigg How could code understanding be an objective thing? Are there people who actually believe a text’s interpretation is independent of the history and knowledge of the interpreter? (OK, sure: there are. Too many, in fact.) (1/4)
During my “literary theory” days, I remember reading Stanley Fish, whose early schtick was “reader-response criticism” (a cool idea). He started out by semi-implicitly claiming that every reader of “Paradise Lost” would react, line by line, the same.
This is obviously silly, but hey those were different times. Theories-of-everything were all the rage. (2/4)
So he invented “interpretive communities” (https://en.wikipedia.org/wiki/Interpretive_communities), which is a formalistic way of saying “people’s history influences how they react to texts”. It seemed to me kind of a deflection, because he dodged the issue of how “community” is an extremely fuzzy category. (3/4)
I’m reminded of poet/programmer Dick Gabriel’s assertion that “a poem is a program that executes in the brain of the reader”. It was his way of saying that of course people who extract meaning from a poem will be referring to their private Postgres instance to do SELECTs on connotations of words, phrases, etc. (4/4)
Very Early On I became Extremely Skeptical of teachers saying that "What the author meant was, …"
And my skepticism seemed largely confirmed by writers who responded to readers comments with positive affirmations regardless of how "crazy" and "offbeat" their comments.
Like, "Whatever it means to you, that's OK with me!" (kinda') says the author — as long as they're getting paid, and you're not attacking them.
@JeffGrigg I broadly agree that “what the author meant” is not a useful move.
But I contrast that with something I read from Isaac Asimov. He’d written a story. He read an analysis of it from some sort of “lit crit” person. He scoffed at it. Then he thought about it and realized, “Yeah, that’s what was actually going on, though I didn’t realize it.”
@paninid@marick@JeffGrigg
Not just poems, obvsly. Everything we hear and see and feel runs like a program in our brain. Internal programs evolved over time. Getting something from another brain specifically, rather than the universe at large, is like loading an external program. It may or may not run the same way in all brains. Prbly not. Memes ‘R’ Us, in other words. Yet poems are rather more subversive than other forms of communication.
@inthehands @paninid@JeffGrigg@marick
50 yrs ago I graduated with a Bachelor in General Studies degree from Big State University. It was a new offering when I started with it. What sold me on it was, no advisor signature required for my course selections. Could take whatever I wanted so long as I didn’t accrue enough credits in a dept. to retroactively qualify for a major. One class was intro to programming, taught by a liberal arts prof. I fell into an IT career by accident.
1/n
@inthehands@paninid@JeffGrigg@marick
I’d sucked at Algebra, failed a logic class, but could read a manual and figure out how to follow the rules to make a program do what I wanted it to do. I learned bits of FORTRAN, SNOBOL, Assembler. I wrote programs that inadvertently discovered bugs in the compilers.
2/n
@inthehands@paninid@JeffGrigg@marick
But my first job was with COBOL. That was easy to pick up. Where all the other classes I took came in handy was when I got to where I was having to figure out what the programs needed to do instead of what I was told to do. I knew nothing about business, or manufacturing, or banking, or engineering, where I’d be working thru the years, but I knew how to ask the questions, and deal with the answers, to design & write the programs.
3/n
@inthehands@paninid@JeffGrigg@marick
But the greatest value I got from my personal liberal education was the idea that I did not need to follow the lock-step path thru management and beyond. I had more interesting things to do when I wasn’t at work, and so I was just a coder, not mngnt, until I switched to end-user support. Again, knowing how to ask the questions after making sure it was plugged in, and rebooting didn’t fix whatever the problem was.
4/n
@inthehands@paninid@JeffGrigg@marick
TBH, I switched to support in ‘92 cuz I knew Y2K was coming and did not want to be a COBOL programmer for that. Coulda made bank for sure, but nope. Not my idea of fun. That was also a lesson from liberal arts, of course. Fun is good. Fun is good for you. Do more fun, live longer and happier. Retired now. Fun has slowed down some, but I’m not bored.
5/5
@qurlyjoe@inthehands@paninid@JeffGrigg SNOBOL! A great language. (Well, based on using it for a week, for fun.) If I remember right, every single statement could be a goto. Put that in your pipe and smoke it, Dijkstra.
Add comment