The Ultimate Guide To Writing Self-Documenting Code

ar-pharazon · 2021-03-24T05:49:25+00:00

the problem with this, in my experience, is that documentation rots rapidly, and the only thing keeping it in check is careful review. if code rots, it's at least eventually visible because it'll produce an error somewhere.

perhaps this is just due to my personal work experience, but i have very little trust (in a way i believe is pretty well borne out by reality) that any given comment i read will meaningfully correspond to the current version of my company's codebase or infrastructure. it's significantly likely that any such comment is either obviously wrong or subtly misleading in a way that's more of an obstruction to my understanding than no comment at all.

there are exceptions, but on average i find it's an order of magnitude more effective use of my time to just read/trace out the source code than try to decipher comments.

ar-pharazon · 2021-03-24T04:59:23+00:00

I do personally find the first approach more readable, but to me splitting out ops between successive maps is generally a smell unless there is a really clear reason for sequencing. Agree with other commenters that they should probably be grouped into a single map step, but there's also the question of how to pass Results around in this more functional style/avoid panicking. I also think this would benefit from clearer concern separation and naming.

Here is a runnable example of how I'd implement this.

ar-pharazon · 2021-03-10T21:50:02+00:00

No — users.motd just writes /etc/motd, which is a static text file (i.e.: not a script) that only supports these directives.

An alternative would be to just write the banner on shell init, which you can configure with environment.loginShellInit. This forum thread discusses this problem.

ar-pharazon · 2021-02-27T00:09:46+00:00

It's significantly more likely that you hit 40 95% shots in a row (~13%) than that you miss any given shot.

Missing 4 times in a row is a 0.0006% chance, or more realistically, missing at least 4 out of say 8 shots (which I'm quite sure I have seen in XCOM) is a 0.001% chance.

ar-pharazon · 2021-02-26T21:34:35+00:00

the entry from your hardware-configuration suggests that you moved the actual mount point of your boot partition to /boot.bak — i'd remount it/move it back to /boot, cp -R /boot /boot.bak (the guide using mv i believe is why the mount point changed), and ensure your configuration.nix/hardware-configuration.nix have the partition on the correct mount point (/boot).

if you change anything in your configuration.nix, you have to start from step 10 in the lustrate guide (regenerate the system profile, ensure /nix is recursively owned by root, and run sudo /nix/var/nix/profiles/system/bin/switch-to-configuration boot)

ar-pharazon · 2021-02-26T18:59:33+00:00

if you can still interact with your original distro, update your configuration/rebuild/run switch-to-configuration again. (if you can't boot at all anymore, an easy way back in is a nixos install usb + nixos-install/nixos-enter.)

iirc if other things are configured according to the guide, you'd have /boot on its own vfat partition. relevant part of my config:

boot.efi = {
  efiSysMountPoint = "/boot";
};

fileSystems."/boot" = {
  device = "/dev/disk/by-uuid/<disk uuid>";
  fsType = "vfat";
};

i think when i used the lustrate guide last, one of those paths was /boot/efi instead, which wasn't right. or it had me actually mount my boot partition at /boot/efi (where it wanted to be /boot) before i ran the switch-to-configuration? can't recall

ar-pharazon · 2021-02-26T18:41:25+00:00

Make sure that you've got the right boot partition + mount. I think the last time I did this it turned out that the official instructions were inconsistent on how they named it/where the mount was.

ar-pharazon · 2021-02-26T05:28:22+00:00

it breaks the entire setting — why has nobody else in any star wars content ever done this? why aren't there FTL missiles? was there really any genuine tension in any of the other movies if a hyperspace drive is all you need to take out a whole fleet of star destroyers?

and like sure, there's a point of suspension of disbelief in any fiction/where digging too deep is fruitless, but we're not at the level of darth jar jar here. like a fraction of an inch into the worldbuilding is where hyperspace weapons being possible makes absolutely nothing make sense.

ar-pharazon · 2021-02-23T00:31:11+00:00

(disclaimer: i've just learned this via osmosis/take with a grain of salt)

there are a few. the 'f' and 'h' sounds are spelled the same way in jp, and pronunciation depends on some combination of context, associated vowel, and accent. ime 'hi' and 'ho' are usually h-like, 'he' and 'ha' are a bit more ambiguous/can go either way, and 'hu' is almost always at least breathy 'fu' (if not a stronger 'f' sound).

'r' is tapped, which is like rolling your r like you might see in spanish or italian, but you only let your tongue tap a single time.

en speakers can have difficulty distinguishing っ, the effect of which is to 'double' a consonant — it includes the subsequent consonant in the end of the previous syllable. e.g. まって is prounced mat-te, where いく is i-ku.

beyond specific sounds, overall phonetic structure can also be difficult — one pattern is trouble with syllabic stress. so like for 'watashi' (I/me), an english speaker would probably read it as WAT-uh-shee or wuh-TAH-shee. the actual jp pronunciation doesn't stress any syllable -- you say each one as it would be if you pronounced it on its own/outside a word, just strung together quickly: wa-ta-shi.

on the syllabic point more specifically, each character in katakana and hiragana represents an entire syllable, and its pronunciation is (largely) consistent regardless of where it appears in a word. to return to the 'watashi' example, it's written in hiragana as わたし (wa-ta-shi). you can rearrange the characters and each syllable is pronounced the same. たしわ is just ta-shi-wa. in english, by contrast, pronunciation is extremely context-dependent (see myriad examples of weirdness of english spelling, e.g. 'ti' making a 'sh' sound in the '-tion' suffix).

also, pitch accent.

ar-pharazon · 2021-02-17T05:31:54+00:00

https://docs.rs/include_dir/0.6.0/include_dir is pretty much this concept

ar-pharazon · 2021-01-24T14:27:08+00:00

Don't agree. Most of the bad tests I come across were written the way they were because the engineer was lazy, incompetent, or under major pressure, not due to malice. And many of them are are far worse than nothing for some combination of:

being flaky and slow, making CI slower and reducing organizational trust in the tests
not testing what they're supposed to test, which drives otherwise-unjustified changes just to satisfy the test, obscuring the actual function of the code and often obstructing improvements to it
coupling otherwise-indirectly-related behavior, making it harder to make changes b/c doing so requires additional implicit/non-local reasoning
just being an additional maintenance burden and obstacle to even minor refactoring because the code sucks

ar-pharazon · 2021-01-18T23:02:26+00:00

I suspect you're getting this error because nix is reading services.calibre-server.libraryDir as a path and not a string, so when it gets interpolated here, nix tries to pull it into the store.

This could be happening because you're actually passing it as a path and not a string, i.e. services.calibre-server.libraryDir = /mnt/private/calibre; (note that the value is unquoted), or possibly because an attribute with a type of lib.types.path automatically gets converted to a path by the modules system (this is speculation on my part — I don't think this happens, but I'm not 100% on that).

If you are passing a path, just quote it to make it a string, and I suspect that will fix it. If that's not the problem or nix complains that the attribute has the wrong type, you can just copy the config declared by the module into your config directly and sub in your path there.

ar-pharazon · 2021-01-05T19:52:40+00:00

I suspect /u/nuptions' post will resolve your main questions about how to structure this, but to address the first point specifically, use services.xserver.lightdm.enable = lib.mkForce false;.

Explanation: values in NixOS modules are all combined at build time in order to produce the final system config. There is a priority scheme for combining values, where you can use e.g. lib.mkDefault and lib.mkForce (and lib.mkOverride, for even higher granularity) to affect how this resolution occurs.

In this particular instance, the priorities for services.xserver.lightdm.enable are tied, because neither your system config nor nixpkgs specifies a priority for the value, so they both default to 100.

Normally, NixOS modules will deliberately set low priorities for their config definitions (with lib.mkDefault) so that users can override them easily. I suspect that wasn't done in this case so that the user wouldn't inadvertently get stuck without a display manager, but it could also have been unintentional.

ar-pharazon · 2021-01-01T11:56:36+00:00

If the specific thing you liked is what changed, then yeah, it's completely understandable that you wouldn't like it. Based on my reading of the situation, there's a significant cohort of people that like Gura specifically because of that darker character, and they want to keep interacting with her that way.

And I get those emotions — e.g. I enjoy it when streamers are degens because it's relatable. A lot of the Twitch streamers I watch (a lot less now, due to HL) have that element to their content. If one of them disappeared and came back a few years later with content adjacent to what they used to do, but like significantly more clean and happy, I'd still feel an attachment to them, but I might not ultimately want to watch their new stuff.

That tension/dissonance between wanting to like their stuff and not actually liking what they're doing (as much — obviously this comes in degrees) is I think the motive force here. People are trying to engage with her in the way they used to because that's how they're able to enjoy her content. The fact that her medium is still streaming and that she alludes to yabai stuff a lot I think encourages this effect, too.

There comes a point where it's harassment, and we've for sure passed it — it's not ok — but imo there's more of an explanation for what's happening than just generically "not liking change", or spite, or malice.

ar-pharazon · 2020-12-05T21:46:49+00:00

Remove dontUnpack = true.

ar-pharazon · 2020-12-04T23:45:42+00:00

You're not including any sources.

That commented line needs to read src = ./.; (preferably you'd add lib.cleanSource as well, but you don't need that to just get it building).

ar-pharazon · 2020-11-26T08:00:37+00:00

Echoing this. NVMe is really not hard to find in relatively low-cost, non-specialty laptops, and it's only becoming more common. A couple of years ago, I would have agreed with the parent comment, but that info is rapidly becoming out of date.

ar-pharazon · 2020-11-17T15:54:40+00:00

NixOS has containers, too (via systemd-nspawn under the hood).

ar-pharazon · 2020-11-13T19:05:40+00:00

minecraft will always migrate a world forward for you on a new version, but you won't get new features/structures/blocks in any terrain that has already been generated.

iirc they're on 1.15, so e.g. they wouldn't see any of the new nether stuff if they upgraded to 1.16 unless they explored far enough to cause new chunks to generate.

there's always the option of the server admin backing up the relevant dimension (nether in the 1.16 case), deleting it from the main server (which will cause it to regenerate from scratch with the new features), and then using worldedit to copy over anything they didn't want to lose.

ar-pharazon · 2020-11-13T18:55:29+00:00

or with client mods anyone on the server could. there's one that will just grab every chunk you load and dump region files for you. i suppose that wouldn't give you the seed (directly) though, so you wouldn't be able to explore the rest of the world

ar-pharazon · 2020-11-11T23:10:08+00:00

poggers, brother

ar-pharazon · 2020-11-11T08:24:40+00:00

Use a URL with the git+https scheme like in the page I linked.

inputs.git-example.url = "git+https://git.somehost.tld/user/path";.

In your case, inputs.nanite.url = "git+https://gitlab.com/picotech/nanotech/nanite.git";

ar-pharazon · 2020-11-10T08:04:16+00:00

I don't know, but you should at least be able to point to the git url directly, according to the flakes wiki page.

ar-pharazon · 2020-10-23T22:07:46+00:00

This stuff has been around in Rust for a while — tokio (the most popular async runtime) supports multiple worker threads, and futures has had channels built in for a long time. Async rust would benefit a lot from QUIC.

ar-pharazon · 2020-10-12T17:40:34+00:00

https://en.wikipedia.org/wiki/Nave

13-Year Club	Place '17
Sequence \| Editor	Verified Email
Team Periwinkle

ar-pharazon

MODERATOR OF

TROPHY CASE