Microblog: A small weblog for frequent
short-thoughts.
The Doc-Comment (Pipe) Dream
I’ve been thinking recently about doc-comments/docstrings,
and how differently they are implemented and formatted. I
know, it’s truly a world of excitement round here!
Godoc has
pretty much no format, inferring much from context, and
deferring further functionality to other tools. A
reflection of Go’s simple, atomic, and slightly
prescriptive approach to language design.
Godoc comments are just good comments, the sort you would
want to read even if godoc didn't exist.
Contrast to D. The idea that syntax isn’t
the main barrier to code understanding extends
to Ddoc
which permits macros, code blocks, and even aligned
tables. In typical D spirit, they have syntax to be
learned, but the resulting comments (though complex) are
readable both in and ex situ.
A valid D comment:
/**
* Prints `Hello, world!` normally, and then `Yellow world!` in yellow.
*
* # Welcome to the Docs
*
* It's great to see you, enjoy your stay.
*
* ## Tables!
*
* | Line No. | Output |
* | -------: | ------------- |
* | 1 | Hello, world! |
* | 2 | $(YELLOW Yellow world!)
*
* ## Lists!
*
* - Lists are:
* * Useful
* * List-y
*
* ## Quotes!
*
* > Comments are hard. -- programmers
*
* Examples:
* ```
* main(); // Let's call that function
* ```
* ``` sh
* # Bourne-shell equiv:
* echo -e 'Hello, world!\n\033[01;33mYellow world!\033[00m'
* ```
*
* - - -
*
* Authors: Finch River, fdriver@posteo.net
*
* Date: 2021-06-05
*/
Despite differing results, the underlying theme is
of in situ readability, and language-suitability.
While D and Go’s great documentation is mostly a testament
to their communities, it’s not a stretch (imo) to say that
languages lacking good commenting conventions have worse
docs (naming no names (Clojure)).
University-Lockdown Blues
I had my final exam for the year a few days ago. I don’t
think that they went well, but I’ve always found it hard
to pre-gauge.
I’m tentative to say this, as I’m lucky to just be
healthy, but this year has been shit. Some say that it’s
like time has almost stopped, but I think I stopped while
life moved on.
Not being able to meet up for groupwork would have been
bad anyway, but our lecturers seem to think that us
digital natives can work at the same speed without
face-to-face contact.
I’m not going to record my lectures; you should be
attending each one anyway.
What a joke.
How should I clearly view a lecture when it competes for
space on my 13” screen with notes and an editor?
How can I even attend lectures reliably when I’m one of 5
people trying to both send and receive real-time video on
one university-house internet connection?
How will I ask a question if the lecturer won’t/can’t use
the Zoom chat panel at the same time as a slideshow?
I’m paying full tuition fees for a shitty YouTube
course.
I can’t even blame my lecturers (for the most part).
They’ve been thrown into this with as little preparation
as me, with far greater responsibilities. That I can’t be
frustrated is what’s so frustrating. If it was a
definitive failure I could at
least be satisfied that I’m angry at the right thing.
Furthermore, it’s just been no fun. I know, woe is
me, but 80% of the enjoyment was making friends and
learning things by talking to people.
My existing friends have also suffered. When I’ve spent my
day on online lectures, online technical difficulties,
online quizzes and short-form work, and hours of
coursework, the last thing that I want is to spend more
time online, even for my favorite people.
But here we are. I think
hope that we’re past the worst. The end is in
sight, rather than nigh. Travel restrictions are lifting,
friends are visiting later this week, and the sun is out.
Wish me luck, and luck to you also!
I Program HTML
I once thought of
HTML as a
data-format written by site/document generators and
masochists.
Yet a friend accused me of being quick to judge. What
cheek! And so I brushed up on HTML5+CSS3 to prove once
again that my opinions are (as usual) perfectly formed now
and forever.
Long-story-short, I’ve become pleased with what just a
little experimenting (and CSS-selectors) can make. HTML
has limitations, but they are healthy if your aim is
simple, semantic web documents. It’s been a while since I
had my own site, and I decided to start one up as a little
passion project.
Please note: I’m no web designer; I’m an internet
person trying my best and having fun. Hopefully you will
too. At least for now, I aim to hand-write (some of) this
site, and make the source as readable (within reason) as
the formatted version, bar color.